Retrieve a single root agent turn to inspect status, time boundaries, errors, and token usage.
Endpoint
GET /agents/sessions/{session_id}/turns/{turn_id}
Returns 200 with a single Turn. The query does not start a model, resume execution, or create resources.
Path parameterssession_idstring (required)Session ID, for example sess_xxxturn_id string (required)Public turn ID, for example turn_xxxThe path hierarchy must match. Turns from another workspace or another caller, and requests whose parent resource does not exist, return no data. | Request example |
Response fieldsidstringPublic turn IDobject stringObject 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; null means no error
Properties code stringError codemessage stringError descriptionobject / nullToken usage; null when the related counts are incomplete
Properties input_tokens integerNumber of input tokens
input_tokens_details cached_tokens integerNumber of input tokens that hit the cacheintegerNumber of output tokens
output_tokens_details reasoning_tokens integerNumber of reasoning tokensintegerTotal number of tokensusage 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.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. | Response example |
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
404 | not_found_error / not_found_error | Confirm that the session and turn exist in the same workspace, and use matching path levels |
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 |