List root agent turns and verify execution status and token usage.
Endpoint
GET /agents/sessions/{session_id}/turns
Returns the root agent's turn list. Returns 200 on success. The query does not start a model, resume execution, or create resources.
Path parameterssession_idstring (required)Session ID, for example sess_xxxQuery parameterslimitinteger (optional)Page size, range 1–100, default 20order string (optional)Sort direction, asc or desc, default descafter string (optional)The last_id from the previous page; the cursor item is excludedbefore is ignored and is not used for reverse pagination. Use order and after to page. | Request example |
Response fieldsList envelope:usage contains input_tokens, input_tokens_details.cached_tokens, output_tokens, output_tokens_details.reasoning_tokens, and total_tokens. If the related counts are incomplete, the entire usage is null.object stringList object type, fixed as listdata array<Turn>Turns on this page; [] when emptyfirst_id string / nullFirst turn ID on this page; null for an empty pagelast_id string / nullLast turn ID on this page; null for an empty page; use it as afterhas_more booleanWhether the current scan direction has another pageTurn fields:waiting is not a successful terminal state. completed, failed, and cancelled are terminal. The SSE turn.created event can show queued; persisted turns start at in_progress.
data item id stringPublic turn IDobject stringTurn object type, fixed as agent.session.turnsession_id stringOwning sessionagent_id stringExecuting agentsubagent_id string / nullSubagent ID, null for a root turnstatus stringTurn status: in_progress, waiting, completed, failed, or cancelledcreated_at integerCreation time, Unix secondsstarted_at/completed_at integer / nullStart and completion time, Unix seconds. null before the boundaryerror object / nullTurn-level error.
Properties code stringError codemessage stringError descriptionobject / nullToken usage.
Properties input_tokens integerNumber of input tokensinput_tokens_details objectInput token details.
Properties cached_tokens integerNumber of input tokens that hit the cacheintegerNumber of output tokensoutput_tokens_details objectOutput token details.
Properties reasoning_tokens integerNumber of reasoning tokensintegerTotal number of tokens | Response example |
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Fix limit and order as described in the query parameters |
404 | not_found_error / not_found_error | Use a valid session ID; use the last_id returned by the previous page as after |
502 | server_error / agents_api_upstream_unavailable | Retry later. If it keeps failing, submit a ticket with the x-request-id from the response headers |