List Sessions

Prerequisites

Endpoint and authentication configuration must be completed. For details, see Overview and authentication.

Endpoint

GET /sessions

Query parameters

Parameter	Required	Type	Default	Description
`agent_id`	No	string	—	Filter by agent
`statuses[]`	No	string	—	Filter by multiple statuses; can be repeated. Example: `?statuses[]=idle&statuses[]=running`
`created_at[gte]` / `created_at[lte]`	No	string	—	Creation time range, ISO 8601
`limit`	No	int	20	Number of items per page, maximum 100
`page`	No	string	—	Omit on the first request; pass `next_page` from the previous response for subsequent requests

Request example

curl "$AGENTSTUDIO_URL/sessions?agent_id=agent_xxx&statuses[]=idle&limit=20" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Response example

{
  "data": [
    {
      "id": "sesn_xxx",
      "type": "session",
      "status": "idle",
      "stop_reason": null,
      "agent": {
        "id": "agent_xxx",
        "type": "agent",
        "version": 1,
        "name": "data-analyst",
        "model": {"id": "qwen3.7-max"},
        "system": "你是数据分析专家，使用 pandas 处理 CSV 文件。",
        "tools": []
      },
      "environment_id": "env_xxx",
      "title": "Q3 销售数据分析",
      "metadata": {"biz_ticket_id": "1234"},
      "archived_at": null,
      "created_at": "2026-05-28T08:23:11.456000Z",
      "updated_at": "2026-05-28T08:23:25.789000Z",
      "environment_variables": {"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"}
    }
  ],
  "next_page": "xxx",
  "request_id": "xxx"
}

The response contains data (an array of Session objects) and next_page (cursor for the next page). Session object fields are as follows:

Session object fields

Field	Type	Description
`id`	string	Session ID, format `sesn_<ULID>`
`type`	string	Fixed as `session`
`status`	string	Session status: `idle` / `running` / `terminated`
`stop_reason`	object \| null	The reason the session returned to `idle`. A discriminated union: `null` (running, or idle and just created) \| `{"type": "end_turn"}` \| `{"type": "retries_exhausted"}` \| `{"type": "requires_action", "pending_batch_id": "...", "pending_call_ids": [...]}`. Only meaningful when `status` is `idle`; see Retrieve Session for full details
`agent`	object	Agent configuration snapshot, including `id`/`version`/`name`/`model`/`system`/`tools`, etc.
`environment_id`	string	The bound environment ID
`title` / `metadata`	string / object	Session title and custom business metadata
`archived_at`	string \| null	Archive time; `null` when not archived
`created_at` / `updated_at`	string	Creation/last update time, ISO 8601
`environment_variables`	object	Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name

​Prerequisites

​Endpoint

​Query parameters

​Request example

​Response example