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 parameterssession_idstring (required)Session ID, for example sess_xxxQuery parameterslimitinteger (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 |
Response fieldsList envelope:objectstringList 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.
data item 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 |
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Fix limit and order as described in the query parameters; use the last_id returned by the previous page as after |
404 | not_found_error / not_found_error | Use a session ID that exists and has not been deleted in the current workspace |
502 | server_error / agents_api_upstream_unavailable | Retry later. If it keeps failing, submit a ticket with the x-request-id from the response headers |