get_assistant_run
Status and result of one headless agent run — an on-demand
run_assistant run, or a scheduled fire (its thread_id is
on get_schedule’s recent_runs).
Only run records are readable here: a web chat or an agent-to-agent thread is
not_found, even inside your organization.
Parameters#
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
thread_id | string | yes | From run_assistant, or a schedule run’s thread_id | |
include_tool_calls | boolean | no | true | Include the per-call list of tools the agent used |
Returns#
json
{
"thread_id": "thread_abc123",
"assistant_id": "assistant_xyz",
"assistant_name": "Maya",
"status": "completed",
"stale": false,
"requested_at": "2026-08-19T09:00:00+00:00",
"started_at": "2026-08-19T09:00:01+00:00",
"completed_at": "2026-08-19T09:01:12+00:00",
"error": null,
"interrupt": null,
"reply": { "message_id": "msg_1", "text": "Yesterday's spend was ...", "created_at": "..." },
"tool_calls": {
"count": 3,
"by_tool": { "get_performance": 2, "recommend_action": 1 },
"items": [{ "tool": "get_performance", "input": "{...}", "success": true, "observation_ref": "obs_..." }]
},
"suggestions": [{ "id": "sa_...", "title": "Pause campaign X", "status": "pending" }],
"attachments": [],
"schedule_id": null,
"schedule_run_id": null,
"tokens": { "prompt": 18234, "completion": 612 }
}status is one of queued, running, completed, failed, interrupted.
interrupted means the agent stopped for a human it could not reach (an
approval or a clarification) — a headless run cannot answer those, so the
colleague’s instructions or tools need adjusting. stale: true means a
queued/running run outlived the worker’s time limit and is reported failed.
Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
not_found | Unknown thread, one outside your organization, or not a headless run |