Skip to main content

Retrieve a subagent

Retrieve a single subagent to inspect its parent agent, public instructions, and lifecycle status.

Endpoint

GET /agents/sessions/{session_id}/subagents/{subagent_id} Returns 200 with a single Subagent. 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, or belongs to another workspace, no data is returned.

Request example

curl "$BASE_URL/agents/sessions/sess_xxx/subagents/subagent_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Response fields

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 closedactive can be idle and waiting; it does not mean the subagent is continuously running. closed_at is null before the subagent is closed.

Response example

{
  "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
}

Error codes

HTTP statusError type / codeSolution
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