Return session status, the agent snapshot, environment summary, and token usage for a session ID.
Endpoint
GET /agents/sessions/{session_id}
Returns 200 and the complete Session object.
Path parameterssession_idstring (required)Session ID. Treat it as an opaque stringThis endpoint has no query parameters. If session_id is malformed, does not exist, has been archived, or belongs to another workspace, the API returns 404. | Request example |
Response fieldsnull when the fields are incomplete. status=idle or HTTP 200 does not fully prove that the previous turn succeeded; also check the turn's terminal state. usage requires all related counts to be present; otherwise the whole field is null.id stringSession ID; reuse it for follow-up turnsobject stringSession object type, fixed as agent.sessioncreated_at integerCreation time in Unix secondslast_active_at integerLast activity time in Unix seconds; not a version number or lockstatus stringSession status: idle, in_progress, requires_action, or failedagent objectEffective agent snapshot.
Properties id stringAgent ID; inline configurations return a session snapshot ID, not a reusable saved agent, and it cannot be retrieved through Agent GETmodel stringModel IDinstructions string / nullCustom instructionsname string / nullDisplay namereasoning object / nullReasoning configuration, contains effort and summarytext object / nullText output configuration; contains format and verbositytools arrayTool configurationmulti_agent object / nullSubagent configuration; contains enabled and max_concurrent_subagentsobjectSafe environment summary; only type for none.
Properties type stringEnvironment type; none or openai_hostedid stringEnvironment ID, omitted when there is no authoritative valuestatus stringEnvironment status: omitted when there is no authoritative valueenvironment_template_id stringEnvironment template ID, omitted when there is no authoritative valueworkspace_directory stringWorkspace directory, omitted when there is no authoritative valueerror string / nullEnvironment error description, omitted when there is no authoritative valuedesktop object / nullDesktop settings; contains enabledcapability_directories array<string> / nullCapability discovery directoriesnetwork object / nullNetwork policy; contains access and allowed_domainspackages object / nullPackage lists; contains npm, python, and systemfiles arraySafe environment file metadataskills arraySafe skill metadataplugins arrayPlugin information; [] for managed environmentsobjectSession metadata; an empty value is {}vault_ids array<string>Vault IDs recorded at creation; this does not mean mounting is completerequired_actions arrayFunction calls that need client handling; [] when empty.
Properties type stringItem type, fixed as function_callturn_id stringPublic turn IDcall_id stringFunction call IDname stringFunction namearguments objectParsed call argumentsstring / nullSession-level error message, different from a turn's structured errorusage object / nullToken usage.
Properties input_tokens integerNumber of input tokensinput_tokens_details objectInput token details.
Properties cached_tokens integerNumber of input tokens that hit the cacheintegerNumber of output tokensoutput_tokens_details objectOutput token details.
Properties reasoning_tokens integerNumber of reasoning tokensintegerTotal number of tokensobjectSpend control; returned only when a historical record has a value; creation and update do not accept writes.
Properties limit integerSpending limit in centsconsumed integer / nullConsumed amount in cents | Response example |
Error codes
Business errors return an error object with type, code, message, and param. Common errors:
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Pass a valid path parameter in the expected format |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | Use a well-formed, non-archived session ID from 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 |