Skip to main content
GET
Get session changes
Long-polls a session for what changed since an event index: new events, status, and the final answer. The server holds the request open until something new arrives or wait_for_seconds expires. Returns 200 with the changes object below, or 204 No Content if no new events arrive within the wait.

Polling rules

  • changes is a delta: each call returns only what is new since from_index. 204 means no new events yet, not that there is no answer.
  • The answer rides the page that delivers the final events, and status can read completed before you reach that page. Keep advancing from_index until the session is terminal and a poll returns no further events.
  • To skip the loop for a finished run, read latest_answer, or use the SDK helper.

Path parameters

string
required
The session ID.

Query parameters

integer
default:"0"
Event index to start from. Pass the next unread index to resume where you left off.
integer
Maximum number of events to return. Minimum 0.
boolean
default:"true"
Whether to include event details in the response.
integer
default:"0"
How long the server holds the request waiting for changes, 0 to 25 seconds. 0 returns immediately, and 20 to 25 gives efficient long polling.

Response

string
Current session status.
string | null
When the agent started executing.
string | null
When the session reached a terminal state.
string | null
Short, stable error message if the session failed or timed out. Branch on error_code, not on this text.
string | null
Failure category when 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. See Outcomes.
string | object | null
The agent’s final result once produced: a string, or an object matching the agent’s answer_format. See Polling rules for when it lands. Mirrored on the session’s latest_answer.
object
Usage and cost so far: steps, total_cost, input_cost, output_cost, reasoning_cost, and cost_per_model[] (per-model name, input_tokens, cached_tokens, output_tokens, reasoning_tokens, and the four costs). Costs are in USD and null when a model’s price is unavailable, so null-check before summing.
object[]
Events since from_index, each in the event shape (type, data, timestamp).
integer | null
Index of new_events[0]. Your next from_index is first_index plus the number of new_events. It equals from_index in the cloud. A local session keeps a window of recent events, so it can be higher there when older events were dropped. null from servers that predate it: count from from_index then.
object[]
The custom tool calls the agent is waiting on, each { tool_name, args, id }, as on status. Empty unless the status is awaiting_tool_results, or paused while calls are pending.

Examples

Response

Long-polling pattern

The SDK helper runs the loop for you: it ends on status (authoritative), streams events from changes, advances from_index, and handles 204 responses.