Skip to main content

List items

List root agent items across turns for result verification and reconnect recovery.

Endpoint

GET /agents/sessions/{session_id}/items Returns root agent items across turns. Subagent items are not mixed in. 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)Number of items per page, default 20, range 1-100order string (optional)Sort direction, asc or desc, default descafter string (optional)The last_id from the previous page; the cursor item is excluded

Request example

curl --get "$BASE_URL/agents/sessions/sess_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 page

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
}

Item types

Every item has id, turn_id, and type. Business fields are at the top level.
typeFields
messagestatus (output status), role (user / assistant), phase (commentary / final_answer / null), and content (array of content parts)
reasoningstatus and summary (array of type=summary_text parts)
function_callstatus, call_id, name, and arguments (arbitrary JSON; can be omitted)
function_call_outputstatus, call_id, output (content array or null; a string tool result is normalized to an array when read), and error (string / null)
command_executionstatus, command, cwd, duration_ms, exit_code, and output
mcp_callstatus, server_label, name, arguments, output, and error
web_search_callstatus and action (search, open_page, find_in_page, or other)
agent_messagesender_agent_id, recipient_agent_id, and content
create_subagent_callstatus, agent_id, content, model, and reasoning_effort
send_subagent_input_callstatus, sender_agent_id, recipient_agent_id, and content
resume_subagent_callstatus, sender_agent_id, and recipient_agent_id
wait_for_subagents_callstatus, sender_agent_id, and recipient_agent_ids
interrupt_subagent_callstatus, sender_agent_id, and recipient_agent_id
close_subagent_callstatus, sender_agent_id, and recipient_agent_id
Content parts use type: input_text and output_text contain text; input_image contains image_url; encrypted_content is not display text. 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. Lists can have a short delay, so recently created data may be briefly unavailable.

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_errorUse a session ID that exists and has not been deleted in the current workspace
502server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with the x-request-id from the response headers