Skip to navigation
WorkflowsRuns

Flows · Workflows · Start a workflow run and return its run ID

View as Markdown

Starts one execution of a published workflow and returns immediately.

This does not wait for the run to finish. Workflows routinely take minutes and can take hours. The response is {workflow_id, correlation_id} where — despite the name — workflow_id is the new RUN ID, a UUID.

input keys must match the workflow’s declared input schema. Keys that do not match are rejected or silently dropped, and a dropped key means the run proceeds without it. Pass {} when the workflow declares no inputs. Do not include a context key; the server injects workspace and user context itself.

Side effects are real and often external — workflows send email, post to Slack, publish content, and consume workspace credits. Do not start one speculatively. Pass idempotency_key when a retry on your side must not produce a second run.

Fails with 400 if the workflow has never been published, and 429 if the workspace is out of credits.

resource: workflow://run-control covers polling and the two-ID confusion.

Authentication

AuthorizationApi-Key

Header authentication of the form Api-Key <token>

OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

workflow_idintegerRequired

Numeric workflow-definition ID from flows_listWorkflows. Not a run ID.

Query parameters

expandstringOptional

Set to token to also receive a scoped JWT that can read this run's details without full credentials.

Request

This endpoint expects an object.
inputmap from strings to anyRequired

Input parameters for this run, as a flat object. The accepted keys and their types are given by the inputs JSON Schema on the workflow returned by flows_listWorkflows — read it first rather than guessing.

Pass {} when the workflow declares no inputs. Do not include a context key; the server injects workspace/user context itself.

versionintegerOptional
Published version to run. Omit to run the latest published version, which is almost always what you want.
correlation_idstringOptional

Your own identifier for correlating this run later. Auto-generated when omitted. Useful when you start many runs and need to match results back to your own records.

idempotency_keystringOptional

Client-supplied key that lets the server collapse duplicate starts. Set this when a retry on your side must not produce a second run.

idempotency_strategystringOptional

How to behave when idempotency_key matches an existing run. Only meaningful alongside idempotency_key.

priorityintegerOptional
Execution priority. Leave unset unless told otherwise.
task_to_domainmap from strings to anyOptional

Advanced routing — pins named tasks to specific worker domains. Leave unset unless you are debugging worker placement.

Response

Run started. workflow_id in the body is the RUN ID.

Errors

400
Bad Request Error
404
Not Found Error
429
Too Many Requests Error