Run Workflow
Available for: Workflow
Runs the deployed Workflow version, in blocking or streaming mode.
Standard API equivalent: Run Workflow. Differences:
workflow_idand any unknown body field are ignored.trace_idandtrace_session_idare accepted.- The request body is capped at 8 MiB.
- The stream omits TTS, human-input, agent-log, and retrieval-resource events. A run that reaches a human-input step fails.
- Error codes differ.
Authorizations
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Headers
Same as the trace_id body field, checked first.
Same as the trace_session_id body field, checked first.
Query Parameters
Same as the trace_id body field, checked after the header.
Same as the trace_session_id body field, checked after the header.
Body
Values for the app's input variables, keyed by variable name. Use the input variables defined in the version currently deployed to the target environment.
Pass a file object for a single-file variable, or an array of file objects for a file-list variable. Each file object has the same structure as an item in files.
End-user identifier, defined by your app and unique within it. Scopes data access: a workflow run and its files are only visible to later requests that carry the same user. See End User Identity.
How the response is delivered.
streaming: events arrive as the run produces them. Use it for anything longer than a quick reply.blocking: one response once the run completes.
streaming, blocking Files to pass to the workflow. For a local file, first upload it via Upload File, then reference the returned id as upload_file_id with transfer_method: local_file.
The workflow's own file settings decide what is accepted, such as the allowed types and how many files. A workflow that accepts no files ignores these entries.
Trace identifier propagated to observability data. Letters, digits, hyphens, and underscores are accepted, up to 128 characters. A value that does not match is skipped, not rejected.
Trace session identifier propagated to observability data, 1 to 200 characters after trimming.
1 - 200Response
The content type and structure depend on the response_mode parameter in the request.
- If
response_modeisblocking, returnsapplication/jsonwith aWorkflowBlockingResponseobject. - If
response_modeisstreaming, returnstext/event-streamwith a stream ofChunkWorkflowEventobjects.
Task ID for this run. In blocking mode it arrives only in this final body, so Stop Workflow Task is practical only with streaming.
The workflow run's ID.