Execute Flow
execute_flowRun a published ServiceNow Flow Designer flow by its scoped name. Use foreground mode for synchronous outputs, or background mode for flows with approval or wait steps, returning a context ID to poll for status.
Instructions
Execute a published ServiceNow Flow Designer flow by scoped name. Runs the flow using sn_fd.FlowAPI via a background script.
In foreground mode (default), the call blocks until the flow completes and returns outputs directly. In background mode, it returns immediately with a context ID that you can poll with get_flow_context_status.
IMPORTANT: Flows with approval or wait steps MUST use background mode — foreground mode will fail if the flow enters a waiting state.
NOTE: This tool requires the flow to be published. If you are iterating and building a flow that may not be published yet, use test_flow instead — it tests the flow in its current draft state, exactly as the 'Test' button in Flow Designer does.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Execution mode. "foreground" (default) runs synchronously and returns outputs when complete. "background" returns immediately with a context ID — use get_flow_context_status to poll, then get_flow_outputs or get_flow_error to retrieve results. Use background for flows with approval/wait steps. | |
| quick | No | Skip creation of execution detail records for better performance. Default false. Use true in CI/CD or when you don't need step-level detail. | |
| scope | No | Scope context for script execution. Can be a scope name (e.g., "x_myapp_custom") or sys_id. Use when the flow is in a scoped app. | |
| inputs | No | Input name-value pairs to pass to the flow/subflow/action. Keys are the input variable names defined in Flow Designer. | |
| timeout | No | Timeout in milliseconds for the execution. Only applies to foreground mode. Default is the ServiceNow server default (~30s). | |
| instance | No | The ServiceNow instance auth alias to use. This is the alias configured via `now-sdk auth --add` (e.g., "myinstance", "prod", "test"). The user will typically refer to this by name when saying things like "on my myinstance instance". If not provided, falls back to the SN_AUTH_ALIAS environment variable. | |
| scoped_name | Yes | Scoped name of the flow/subflow/action to execute (e.g., "global.my_flow", "x_myapp_custom.create_incident_subflow"). |