Skip to main content

List subagents

List a session's subagents and inspect names, status, and lifecycle timestamps.

Endpoint

GET /agents/sessions/{session_id}/subagents Returns the session's subagent list. The root agent is not returned as a 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_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/subagents" \
  -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<Subagent>Subagents on this page; [] when emptyfirst_id string / nullFirst subagent ID on this page; null for an empty pagelast_id string / nullLast subagent ID on this page; null for an empty page; use it as afterhas_more booleanWhether the current scan direction has another pageSubagent fields:active can be idle and waiting; it does not mean the subagent is continuously running. History queries do not start or resume subagents.
id stringStable subagent IDobject stringSubagent object type, fixed as agent.session.subagentsession_id stringOwning sessionparent_agent_id stringParent agentname string / nullDisplay nameinstructions array / nullPublic instruction contentstatus stringSubagent status: active or closedopened_at integerOpen time in Unix secondsclosed_at integer / nullClose time in Unix seconds; null before the subagent is closed

Response example

{
  "object": "list",
  "data": [
    {
      "id": "subagent_xxx",
      "object": "agent.session.subagent",
      "session_id": "sess_xxx",
      "parent_agent_id": "agent_xxx",
      "name": "researcher",
      "instructions": null,
      "status": "active",
      "opened_at": 1794118835,
      "closed_at": null
    }
  ],
  "first_id": "subagent_xxx",
  "last_id": "subagent_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_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