Skip to main content

List subagent items

List items across turns for a specific subagent; tool execution records stay separate from root agent items.

Endpoint

GET /agents/sessions/{session_id}/subagents/{subagent_id}/items Returns items across turns for a specific subagent. Subagent tool execution records stay under the subagent path and are not mixed into root agent items. 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/items" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "order=asc"

Response fields

List envelope:object stringList object type, fixed as listdata array<Item>Items on this page; [] when emptyfirst_id string / nullFirst item ID on this page; null for an empty pagelast_id string / nullLast item ID on this page; null for an empty page; use it as afterhas_more booleanWhether the current scan direction has another pageEvery item has id, turn_id, and type. Business fields are at the top level. For item types and content parts, see List Items.Persisted items use final content. SSE item.added can show an in-progress item; an unfinished real-time item is not guaranteed to appear in the list.

Response example

{
  "object": "list",
  "data": [
    {
      "id": "msg_xxx",
      "turn_id": "turn_xxx",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "phase": "final_answer",
      "content": [{"type": "output_text", "text": "Done"}]
    }
  ],
  "first_id": "msg_xxx",
  "last_id": "msg_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