Skip to main content

List subagent turns

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 parameters

session_id string (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 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/subagents/subagent_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 / 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

Response example

{
  "object": "list",
  "data": [
    {
      "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
      }
    }
  ],
  "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; use the last_id returned by the previous page as after
404not_found_error / not_found_errorConfirm that the session and subagent 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