Start an orchestration run

POST 
/v1/projects/:project_id/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/succeeded/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.