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#

In web and embedded chats, a pending run durably pauses the conversation. A worker automatically resumes it when the run ends, with a hard 15-minute deadline measured from the first wait. Closing the browser does not cancel it. A new user message or Stop cancels the continuation. Expiry ends the wait and posts a timeout notice; it does not cancel the independent background run.

For external MCP clients and headless callers, the bounded wait returns early on completion, failure, interruption, or an access error. If it returns queued or running, continue waiting with the same thread ID. A positive wait sets wait_pending: true when its deadline expires before the run finishes. Immediate snapshots do not carry this waiting exemption.

Returns#

{
  "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#