Retrieve Session API: GET /sessions/{session_id}-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Returns session metadata, the embedded agent snapshot, and resource list. Event history and message content are retrieved through the Event API.

Prerequisites

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

Endpoint

GET /sessions/{session_id}

Request example

bash

curl "$AGENTSTUDIO_URL/sessions/sesn_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

python

session = client.sessions.retrieve("sesn_xxx")
print(session.id, session.status, session.title)

java

Session session = client.sessions().retrieve("sesn_xxx");
System.out.println(session.getId() + " " + session.getStatus() + " " + session.getTitle());

Response example

{
  "id": "sesn_xxx",
  "type": "session",
  "status": "idle",
  "stop_reason": {
    "type": "requires_action",
    "pending_batch_id": "response_xxx:9f2c...",
    "pending_call_ids": ["call_xxx"]
  },
  "agent": {
    "id": "agent_xxx",
    "type": "agent",
    "version": 1,
    "name": "data-analyst",
    "description": null,
    "model": {"id": "qwen3-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:11Z",
  "updated_at": "2026-05-28T08:23:25Z",
  "request_id": "xxx",
  "environment_variables": {"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"}
}

The response is a Session object with the following fields:

Response 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 with no end reason yet) \| `{"type": "end_turn"}` (model ended on its own) \| `{"type": "retries_exhausted"}` (retries exhausted) \| `{"type": "requires_action", "pending_batch_id": "...", "pending_call_ids": [...]}` (waiting for tool approval). Only meaningful when `status` is `idle`; `null` when `running`. `terminated` is a terminal state and the server may retain the previous value — clients should not rely on or interpret it. The `requires_action` branch carries a non-empty `pending_batch_id` and `pending_call_ids`; use them to locate the pending approval calls and fetch the corresponding `tool_approval_request` events via the Event API
`agent`	object	Full agent configuration snapshot (locked at creation), 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
`request_id`	string	Unique identifier for this request
`environment_variables`	object	Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name