Skip to main content

List sessions

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 parameters

limit integer (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

curl -sS "$BASE_URL/agents/sessions?limit=20&order=desc&agent_id=agent_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

Response fields

object stringList 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 page

Session fields

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.
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_subagents
environment objectSafe environment summary; only type for none.
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 environments
metadata objectSession 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.
type stringItem type, fixed as function_callturn_id stringPublic turn IDcall_id stringFunction call IDname stringFunction namearguments objectParsed call arguments
error string / nullSession-level error message, different from a turn's structured errorusage object / nullToken usage.
input_tokens integerNumber of input tokensinput_tokens_details objectInput token details.
cached_tokens integerNumber of input tokens that hit the cache
output_tokens integerNumber of output tokensoutput_tokens_details objectOutput token details.
reasoning_tokens integerNumber of reasoning tokens
total_tokens integerTotal number of tokens
spend_control objectSpend control; returned only when a historical record has a value; creation and update do not accept writes.
limit integerSpending limit in centsconsumed integer / nullConsumed amount in cents
null when the fields are incomplete.

Response example

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Error codes

Business errors return an error object with type, code, message, and param. Common errors:
HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorFix limit, order, and agent_id as described, and remove duplicate parameters
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorConfirm that the parent resource exists in the current workspace; use the last_id from the previous page as after
502server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with the x-request-id from the response headers