get_run_status
Poll the status of a workflow run. The run is finished when status is completed (with output) or failed (with error).
Parameters#
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
run_id | string | yes | Run id (agent_run_…) |
Returns (running)#
json
{
"run_id": "agent_run_xyz",
"status": "running",
"created_at": "2026-04-22T14:00:00Z"
}Returns (completed)#
json
{
"run_id": "agent_run_xyz",
"status": "completed",
"created_at": "2026-04-22T14:00:00Z",
"output": {
"company": "Example Corp",
"role": "Head of Growth",
"seniority": "Director"
},
"completed_at": "2026-04-22T14:00:08Z",
"duration_seconds": 8.4
}Returns (failed)#
json
{
"run_id": "agent_run_xyz",
"status": "failed",
"created_at": "2026-04-22T14:00:00Z",
"error": "No company found for email lead@example.com",
"completed_at": "2026-04-22T14:00:03Z"
}| Field | Description |
|---|---|
status | pending, running, completed, failed, or cancelled |
output | Present only on completed. Shape matches the workflow’s output_schema |
error | Present only on failed. Pulled from the failing node’s output |
duration_seconds | Present on completed |
Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
not_found | Run id doesn’t exist or belongs to another org |
Polling pattern#
plaintext
loop:
result = get_run_status(run_id)
if result.status in ("completed", "failed", "cancelled"): break
sleep 1 secondMost workflows complete in 1–30 seconds. A handful of data-heavy workflows (e.g. multi-step LLM chains) run for up to ~2 minutes.
Example#
Request: { "run_id": "agent_run_xyz" }
Response: see “Returns” sections above.
See also#
run_workflow— kick off a runget_workflow— inspectoutput_schemabefore interpretingoutput