Skip to main content

Retrieve a turn

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 parameters

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

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

Response fields

id stringPublic 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
code stringError codemessage stringError description
usage object / nullToken usage; null when the related counts are incomplete
input_tokens integerNumber of input tokens
cached_tokens integerNumber of input tokens that hit the cache
output_tokens integerNumber of output tokens
reasoning_tokens integerNumber of reasoning tokens
total_tokens integerTotal number of tokens
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.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": null,
  "status": "completed",
  "created_at": 1794118835,
  "started_at": 1794118836,
  "completed_at": 1794118840,
  "error": null,
  "usage": {
    "input_tokens": 1024,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 256,
    "output_tokens_details": {"reasoning_tokens": 64},
    "total_tokens": 1280
  }
}

Error codes

HTTP statusError type / codeSolution
404not_found_error / not_found_errorConfirm that the session 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