get_session-获取会话--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

请输入

会话 (Sessions)

get_session-获取会话

概述

/api/v1/sessions/{id} 接口用于获取指定会话的详情信息，包括会话元信息、消息数量、提交次数、记忆提取统计和 Token 使用情况。
该接口适用于在业务系统中查看会话状态、确认会话是否存在，以及对接会话详情页。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口获取会话详情。

请求接口

URI

/api/v1/sessions/{id}
统一资源标识符。

请求方法

GET
客户端对服务器请求的操作类型。

请求头

参数	值	说明
Authorization	`Bearer {api_key}`	鉴权
X-OpenViking-Agent	`{agent_id}`	Agent ID

请求参数

参数	类型	位置	必选	默认值	备注
id	string	Path	是	--	会话 ID
auto_create	bool	Query	否	false	会话不存在时是否自动创建。`true` 时，若目标会话不存在，则自动创建后返回。

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的数据对象
result.session_id	会话 ID
result.created_at	创建时间
result.updated_at	最近更新时间
result.message_count	消息数量
result.commit_count	提交次数
result.memories_extracted	各类记忆提取统计
result.last_commit_at	最近一次提交时间
result.llm_token_usage	历史 Token 使用统计
result.pending_tokens	当前未归档消息对应的估算 Token 数
result.user	当前会话所属身份信息
error	失败时返回的错误对象
error.code	错误码字符串，常见值见下表
error.message	可读的错误描述

常见错误码

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
NOT_FOUND	指定会话不存在，且 `auto_create=false`
INVALID_ARGUMENT	路径或查询参数格式错误

完整示例

示例一：获取已有会话

curl -X GET `https://xxx/api/v1/sessions/a1b2c3d4` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}"

执行成功返回：

{
  "status": "ok",
  "result": {
    "session_id": "a1b2c3d4",
    "created_at": "2026-03-23T10:00:00+08:00",
    "updated_at": "2026-03-23T11:30:00+08:00",
    "message_count": 5,
    "commit_count": 3,
    "memories_extracted": {
      "profile": 1,
      "preferences": 2,
      "entities": 3,
      "events": 1,
      "cases": 2,
      "patterns": 1,
      "tools": 0,
      "skills": 0,
      "total": 10
    },
    "last_commit_at": "2026-03-23T11:00:00+08:00",
    "llm_token_usage": {
      "prompt_tokens": 5200,
      "completion_tokens": 1800,
      "total_tokens": 7000
    },
    "pending_tokens": 128,
    "user": {
      "account_id": "default",
      "user_id": "alice",
      "agent_id": "default"
    }
  }
}

示例二：会话不存在

curl -X GET `https://xxx/api/v1/sessions/not-exists` \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}"

执行失败返回：

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Session not-exists not found"
  }
}

最近更新时间：2026.05.26 11:19:27

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

前置条件 #

请求接口 #

URI #

请求方法 #

请求头 #

请求参数 #

响应消息 #

常见错误码 #

完整示例 #

示例一：获取已有会话 #

示例二：会话不存在 #

概述