List turns for a specific subagent and verify status, time boundaries, and token usage.
Endpoint
GET /agents/sessions/{session_id}/subagents/{subagent_id}/turns
Returns turns for a specific subagent. Returns 200 on success. 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_xxxThe path hierarchy must match. If the subagent does not belong to the session, no data is returned.Query 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 / 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 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; use the last_id returned by the previous page as after |
404 | not_found_error / not_found_error | Confirm that the session and subagent 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 |