火山方舟
火山方舟
API参考
请输入
- 文档首页
火山方舟Managed Agents APISessions会话事件查询会话事件列表
复制全文
下载 pdf查询会话事件列表
文档反馈
问问助手GET https://ark.cn-beijing.volces.com/api/v3/sessions/{session_id}/events
分页查询会话主线程中已经产生的事件，同时返回子 Agent 线程中需要客户端处理的事件。支持按事件处理时间和事件类型筛选。返回范围如下：
- 会话主线程的事件完整返回。
- 子 Agent 线程返回生命周期、协作消息、自定义工具调用和需要客户端处理的工具授权事件。
- 自托管 Environment 中需要宿主执行的内置工具调用也会返回。
子 Agent 线程的思考、普通回复、Span 和预览帧不会在本接口完整展开，服务端生成的工具执行结果也不展开，请使用 获取线程事件列表 查询。客户端回传的工具结果和工具授权回复仍会返回，便于核对结果是否已送达。
说明
- 默认按事件产生时间正序返回（从旧到新）。
- 线程相关事件通过 session_thread_id 标识所属线程。
- 自托管 Worker 按 tool_use_id 回传内置工具结果，不依赖 session_thread_id。
- 实时接收事件请使用 流式获取会话事件。
- 返回字段随事件类型变化，详情请参见 会话事件结构参考。
鉴权
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数
Path 参数
session_id string 必选 | 会话 ID
填写要查询事件的会话 ID，形如 sesn-...
Query 参数
在 URL Query String 中传入。
created_at[gt] string | 起始时间（不含）
事件处理时间的起始边界（不含），采用 RFC 3339 格式。同时传入多个时间边界时，仅返回满足全部边界条件的事件
created_at[gte] string | 起始时间（含）
事件处理时间的起始边界（含），采用 RFC 3339 格式。同时传入多个时间边界时，仅返回满足全部边界条件的事件
created_at[lt] string | 结束时间（不含）
事件处理时间的结束边界（不含），采用 RFC 3339 格式。同时传入多个时间边界时，仅返回满足全部边界条件的事件
created_at[lte] string | 结束时间（含）
事件处理时间的结束边界（含），采用 RFC 3339 格式。同时传入多个时间边界时，仅返回满足全部边界条件的事件
limit integer 默认值 50 | 每页事件数
每页返回的事件数量。
说明
当 limit 大于 200 时，服务端会按 200 处理，不会返回参数错误。
取值范围：[1, 200]
order string 默认值 asc | 排序方向
排序方向，asc 按事件产生时间正序（从旧到新），desc 倒序。
page string | 下一页标识
下一页标识。请将上一页返回的 next_page 原样传入；不传则从第一页开始
types string[] | 事件类型筛选
响应参数
data object[] | 事件列表
本接口返回会话主线程的事件。返回范围如下：
- 会话主线程的事件完整返回。
- 子 Agent 线程返回生命周期、协作消息、自定义工具调用和需要客户端处理的工具授权事件。
- 自托管 Environment 中需要宿主执行的内置工具调用也会返回。
每个事件对象包含 id、type、processed_at 和随 type 变化的业务字段。
只有对应事件结构明确包含时，才会返回 session_thread_id；会话主线程中的常规消息通常不含该字段。
id string | 事件 ID
data.id
事件唯一标识符，形如 sevt-...
processed_at string | 处理时间
data.processed_at
事件处理时间，采用 RFC 3339 格式
type string | 事件类型
data.type
事件类型（如 user.message、agent.message、session.status_idle 等）
next_page string | 下一页标识
下一页标识，请原样传入下一次请求的 page 参数；无更多数据时不返回该字段
获取会话事件列表
发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！
Request
cURL
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions/<SESSION_ID>/events?limit=50&order=asc&types=user.message&types=agent.message" \
-H "Authorization: Bearer $ARK_API_KEY"Response
{
"data": [
{
"id": "sevt-20260926143025-a1b2c",
"type": "user.message",
"processed_at": "2026-09-26T14:30:25.123Z",
"session_id": "<SESSION_ID>",
"content": [{"type": "text", "text": "帮我梳理 Q3 目标"}]
},
{
"id": "sevt-20260926143027-c3d4e",
"type": "agent.message",
"processed_at": "2026-09-26T14:30:27.045Z",
"content": [
{"type": "text", "text": "好的，我先按 OKR 分层梳理，随后逐条给出交付判据。"}
]
}
]
}最近更新时间：2026.11.04 18:12:41
这个页面对您有帮助吗？
有用
有用
无用
无用