Skip to main content

Retrieve a subagent turn

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 parameters

session_id string (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

curl "$BASE_URL/agents/sessions/sess_xxx/subagents/subagent_xxx/turns/turn_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Response fields

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.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.
code stringError codemessage stringError description
usage object / nullToken usage.
input_tokens integerNumber of input tokensinput_tokens_details objectInput token details.
cached_tokens integerNumber of input tokens that hit the cache
output_tokens integerNumber of output tokensoutput_tokens_details objectOutput token details.
reasoning_tokens integerNumber of reasoning tokens
total_tokens integerTotal number of tokens
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

{
  "id": "turn_xxx",
  "object": "agent.session.turn",
  "session_id": "sess_xxx",
  "agent_id": "agent_xxx",
  "subagent_id": "subagent_xxx",
  "status": "completed",
  "created_at": 1794118835,
  "started_at": 1794118836,
  "completed_at": 1794118840,
  "error": null,
  "usage": {
    "input_tokens": 512,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 128,
    "output_tokens_details": {"reasoning_tokens": 32},
    "total_tokens": 640
  }
}

Error codes

HTTP statusError type / codeSolution
404not_found_error / not_found_errorConfirm that the session, subagent, and turn exist in the same workspace, and use matching path levels
502server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with the x-request-id from the response headers