Skip to main content

Get Session

Retrieve details for a specified session

GET
/api/v1/agentstudio/sessions/{session_id}
cURL
curl --request GET \
  --url 'https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio/sessions/{session_id}' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
{
  "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.8-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"
  },
  "vault_ids": [
    "vlt_xxx"
  ],
  "mcp_configs": [
    {
      "mcp_server_name": "weather",
      "headers": {
        "X-Tenant-Id": "tenant-demo"
      }
    }
  ]
}

stop_reason values

The reason the session returned to idle; a discriminated union. stop_reason is used to determine interactivity only when idle; it is null while running; terminated is a terminal state in which the API may retain the previous value — do not rely on or interpret it.
typeDescriptionAdditional fields
nullrunning, or idle just after creation with no end reason yet—
end_turnThe model ended the turn on its own—
retries_exhaustedRetries exhausted—
requires_actionWaiting for tool approvalpending_batch_id, pending_call_ids (both non-empty)
When requires_action, use pending_batch_id + pending_call_ids to locate the calls awaiting a decision, then fetch the corresponding tool_approval_request via the events API. All approval batch/call IDs are non-empty. Malformed objects fail validation; all of the following are invalid:
ExampleReason
{}Missing type
{"type":"requires_action"}Missing pending_batch_id / pending_call_ids
{"type":"requires_action","pending_call_ids":[]}pending_call_ids is empty
{"type":"requires_action","pending_batch_id":"","pending_call_ids":["call_xxx"]}Empty batch ID
{"type":"requires_action","pending_batch_id":"b","pending_call_ids":[""]}pending_call_ids contains an empty item
{"type":"end_turn","pending_batch_id":"b","pending_call_ids":["c"]}Terminal state carrying pending fields
requires_action must include both a non-empty pending_batch_id and non-empty pending_call_ids; other types must not carry pending fields.

Authorizations

​
string
header
required

DashScope API Key

Path Parameters

​
string
required

Response

200-application/json
​
string

会话 ID，格式 sesn_<ULID>

​
string

固定为 session

​
enum<string>

会话状态：idle / running / terminated

Available options:idle,running,terminated
​
end_turn / retries_exhausted

会话回到 idle 的原因（判别联合）。详见 stop_reason 取值。仅 requires_action 携带 pending_batch_id 与非空 pending_call_ids

​
object

智能体配置完整快照，含 id/version/name/model/system/tools 等；会话级覆盖（若已设置）已并入快照

​
string

绑定的运行环境 ID

​
string

会话标题

​
object

业务自定义元数据

​
string | null

归档时间，未归档时为 null

​
string

创建时间，ISO 8601

​
string

最近更新时间，ISO 8601

​
string

本次请求的唯一标识

​
object

会话运行时注入的环境变量

​
string[]

绑定的 Vault ID 列表

​
object[]

会话级 MCP 请求头，未配置时为空数组