Retrieve a single turn for a specific subagent to inspect status, time boundaries, errors, and token usage.
Endpoint
GET /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}
Returns 200 with a single Turn. The query does not start or resume a subagent, and does not create resources.
Path parameterssession_idstring (required)Session ID, for example sess_xxxsubagent_id string (required)Stable subagent ID, for example subagent_xxxturn_id string (required)Public turn ID, for example turn_xxxThe path hierarchy must match. If the turn does not belong to the subagent or the session, no data is returned. | Request example |
Response fieldsusage 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.id stringPublic turn IDobject stringTurn object type, fixed as agent.session.turnsession_id stringOwning sessionagent_id stringExecuting agentsubagent_id string / nullThe corresponding subagent ID for a subagent 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 tokenswaiting 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, subagent, 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 |