List sessions in the current workspace with pagination, optionally filtered by agent.
Endpoint
GET /agents/sessions
Returns 200 and a list envelope. data is an array of Session objects.
Query parameterslimitinteger (optional)Number of items per page, default 20, range 1..100; an empty string or a value outside the range returns 400order string (optional)Sort direction, asc or desc, default desc; an invalid value returns 400after string (optional)Resource ID cursor, up to 256 bytes and not blank; the cursor item is excludedagent_id string (optional)Agent ID filter, filter by saved or inline agent ID, an explicit empty value is invalid, and duplicates return 400For the first page, omit after. For later pages, pass the last_id from the previous response. The list is sorted by (created_at, resource ID). Other unknown query parameters such as before are ignored; use order and after for reverse pagination.A newly created session may not appear in the list immediately. To confirm the latest state, use Retrieve Session. The list does not provide a global snapshot or immediate visibility guarantee. | Request example |
Response fieldsobjectstringList object type, fixed as listdata arraySession objects on this page; [] when emptyfirst_id string / nullID of the first item; null for an empty pagelast_id string / nullID of the last item; null for an empty page; use it for the next afterhas_more booleanWhether the current scan direction has another pageSession fieldsidstringSession 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 centsnull when the fields are incomplete. | 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 | Fix limit, order, and agent_id as described, and remove duplicate parameters |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | Confirm that the parent resource exists in the current workspace; use the last_id from the previous page as after |
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 |