Skip to main content
GET
Get session status
Returns only a session’s live status: state, step count, token usage, and subagent IDs. It is the cheapest liveness check, and it never carries the answer. To follow a run and read its answer, long-poll changes instead. Returns the status object below.

Path parameters

string
required
The session ID.

Response

string
required
Current state: queued, pending, running, paused, idle, awaiting_tool_results, completed, failed, timed_out, or interrupted. See Lifecycle.
string | null
Short, stable error message if the session failed or timed out. Branch on error_code, not on this text.
string | null
Machine-readable failure category if the session failed or timed out: environment_error, no_answer, answer_validation, timeout, insufficient_credit, or internal. See Session failures.
string | null
The agent’s self-assessed outcome, reported with its final answer: success, partial, infeasible, or blocked. null until reported. See Outcomes.
integer
Steps taken so far, where each step is one decide-and-act cycle.
object[]
Per-model token usage: name, input_tokens, cached_tokens (input served from the prompt cache, billed at a discount), output_tokens, and reasoning_tokens. Empty until the agent calls a model.
string[]
IDs of the child sessions this session spawned. List them with their agent labels via GET /sessions?parent_session_id={id}.

Examples

Response

Polling

Poll every 2 to 5 seconds, backing off to 10 to 15 seconds for runs over 10 minutes. Once the status is terminal, read the answer from latest_answer.