Runs
A Run is a single invocation of an agent — the unit you
start, observe, and get output from. Create one with POST /v1/runs.
Lifecycle
Section titled “Lifecycle”A run moves through a small set of states:
state |
Terminal? | Meaning |
|---|---|---|
pending |
no | Accepted, not yet started. |
active |
no | Running (possibly waiting on input or a sub-task). |
closed |
yes | Finished successfully — output is populated. |
failed |
yes | Errored — see failureReason / failureCategory. |
abandoned |
yes | Cancelled. |
Status
Section titled “Status”For a caller-facing view, a run also exposes a derived status:
queued → running → succeeded (or failed / canceled), plus
input_required when it’s blocked waiting for a human response. This is what the
stream’s terminal event and
webhook payloads report.
Getting the result
Section titled “Getting the result”- Wait inline with
Prefer: wait. - Poll
GET /v1/runs/{runId}untilstateis terminal. - Stream
GET /v1/runs/{runId}/stream. - Webhook on completion.
A run’s messages, tasks, and artifacts are all addressable under
/v1/runs/{runId}/… — see the API reference.