查询 Event 历史

分页查询 Forward Session 的事件历史。

GET /api/v1/forward/sessions/{session_id}/events

返回 Session 事件并支持游标分页与字段级过滤。若 Session 开启了旧版增量流式 (incremental_streaming_enabled)，则响应也包含旧版增量事件；通过 event_deltas[] 订阅的流式增量事件不出现在历史查询结果中。

​

请求头

Header	是否必填	说明
Authorization	是	Bearer <PAT>

​

路径参数

参数	类型	是否必填	说明
session_id	string	是	Session ID。

​

查询参数

参数	类型	是否必填	默认值	说明
limit	integer	否	20	分页大小，最大 100。
after_id	string	否	-	返回该 Event ID 之后的事件。
before_id	string	否	-	返回该 Event ID 之前的事件。
order	string	否	asc	排序方向：asc 或 desc。
type	string	否	-	按 Event 类型过滤，支持逗号分隔。
types[]	string	否	-	数组形式的 Event 类型过滤。
include_tool_calls	boolean	否	true	是否包含工具调用类事件。
include_thinking	boolean	否	true	是否包含思考过程事件。

​

示例请求

curl -s -X GET 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/events' \
  -H "Authorization: Bearer $QODER_PAT"

​

示例响应

HTTP 200 OK

{
  "data": [
    {
      "id": "evt_xxx",
      "type": "agent.message",
      "session_id": "sess_xxx",
      "content": [
        {
          "type": "text",
          "text": "Here is the analysis result."
        }
      ],
      "processed_at": "2026-06-22T11:00:03Z"
    }
  ],
  "first_id": "evt_xxx",
  "last_id": "evt_xxx",
  "has_more": false
}

​

响应字段

字段	类型	说明
data	array	当前页的 Event 对象。
first_id	string | null	当前页第一条 Event ID。
last_id	string | null	当前页最后一条 Event ID。
has_more	boolean	是否还有更多记录。

​

Event 对象字段

字段	类型	说明
id	string	Event ID。
type	string	Event 类型。
session_id	string	Session ID。
processed_at	string	事件处理时间；部分事件可能没有该字段。
content	array	message 类事件会返回。

​

按类型允许的 payload 字段

下表字段不包含通用 envelope 字段 id、type、session_id、processed_at。

Event 类型	payload 字段
user.message	content、file_attachments
user.interrupt	reason
user.tool_confirmation	tool_use_id、result、deny_message
user.tool_result	tool_use_id、content、is_error
user.custom_tool_result	custom_tool_use_id、content、is_error
user.define_outcome	description、rubric、outcome_id、max_iterations
system.message	content
agent.message	content
agent.thinking	thinking、text
agent.message_start	message_id、message
agent.content_block_start	message_id、index、content_block
agent.content_block_delta	message_id、index、delta
agent.content_block_stop	message_id、index
agent.message_delta	message_id、delta、usage
agent.message_stop	message_id
event_start	event
event_delta	event_id、delta
agent.tool_use	name、input、evaluated_permission
agent.tool_result	tool_use_id、content、is_error
agent.custom_tool_use	name、input
agent.mcp_tool_use	mcp_server_name、name、input、evaluated_permission
agent.mcp_tool_result	mcp_tool_use_id、content、is_error
agent.artifact_delivered	file_id、original_filename、size、content_type
session.status_running	无
session.status_idle	stop_reason
session.status_terminated	无
session.error	error
session.updated	agent、metadata、title
未知类型	仅返回 envelope，不返回运行时私有原始 payload。

event_start 和 event_delta 仅在通过 event_deltas[] 订阅 SSE 时返回，不出现在历史查询结果中。

​

错误

HTTP	Type	Code	触发条件
400	invalid_request_error	invalid_event_cursor	游标不属于当前 Session。
400	invalid_request_error	invalid_pagination	分页参数不合法。
404	not_found_error	session_not_found	Session 不存在。
401	authentication_error	authentication_required	PAT 无效或已过期。

​

注意事项

• 未知 Event 类型不会导致请求失败；可用时会以最小 envelope 返回。
• Forward 默认过滤 agent ID、environment ID、resources、vaults、worker、trace、raw/debug/internal 等运行时私有字段。

​

相关

发送 Session Events

订阅 Session Events