Skip to main content

List turns

List root agent turns and verify execution status and token usage.

Endpoint

GET /agents/sessions/{session_id}/turns Returns the root agent's turn list. Returns 200 on success. The query does not start a model, resume execution, or create resources.

Path parameters

session_id string (required)Session ID, for example sess_xxx

Query parameters

limit integer (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

curl --get "$BASE_URL/agents/sessions/sess_xxx/turns" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "order=asc"

Response fields

List 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.
id stringPublic turn IDobject stringTurn object 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.
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

Response example

{
  "object": "list",
  "data": [
    {
      "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
      }
    }
  ],
  "first_id": "turn_xxx",
  "last_id": "turn_xxx",
  "has_more": false
}
{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Error codes

HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorFix limit and order as described in the query parameters
404not_found_error / not_found_errorUse a valid session ID; use the last_id returned by the previous page as after
502server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with the x-request-id from the response headers