Start an orchestration run

POST 
/api/v1/orchestration-runs

Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status "queued" (a worker then claims it and moves it to "running") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/completed/failed). Delay and poll waits park the run as "sleeping" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state.

Request

Responses

200

Duplicate request — the run the idempotency_key already names is returned and no second run is started.

201

Run created and executed

400

Validation error (e.g. a tool_context key that cannot become a header, metadata that is not a JSON object, or an idempotency_key that is not a non-empty string of at most 255 characters). No run is created.

401

Unauthorized

403

Forbidden

404

Orchestration not found

409

IDEMPOTENCY_KEY_REUSED — the key is already claimed by a run started from a different request. No run is created.

413

REQUEST_REJECTED — the request body is over the size the body parser accepts

429

QUOTA_EXCEEDED — a requests quota on the calling API key or its project is spent for the window; Retry-After says when it reopens

Response Headers

Retry-After

Seconds until the quota window admits a request again

500

Unexpected server error — INTERNAL_ERROR, with the raw message never forwarded