查询 Event 历史

GET /api/v1/forward/sessions/{session_id}/events 返回 Session 事件历史，并应用字段级过滤。开启增量流式的 Session 会在历史中包含已产生的增量事件。

请求头

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`、`session_thread_id`
`user.tool_confirmation`	`tool_use_id`、`result`、`deny_message`、`session_thread_id`
`user.tool_result`	`tool_use_id`、`content`、`is_error`、`session_thread_id`
`user.custom_tool_result`	`custom_tool_use_id`、`content`、`is_error`、`session_thread_id`
`user.define_outcome`	`description`、`rubric`、`outcome_id`、`max_iterations`
`system.message`	`content`
`agent.message`	`content`
`agent.thinking`	无
`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`
`agent.tool_use`	`name`、`input`、`evaluated_permission`、`session_thread_id`
`agent.tool_result`	`tool_use_id`、`content`、`is_error`
`agent.custom_tool_use`	`name`、`input`、`session_thread_id`
`agent.mcp_tool_use`	`mcp_server_name`、`name`、`input`、`evaluated_permission`、`session_thread_id`
`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。

错误

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 等运行时私有字段。

查询 Event 历史

请求头

路径参数

查询参数

示例请求

示例响应

响应字段

Event 对象字段

按类型允许的 payload 字段

错误

注意事项

相关

发送 Session Events

订阅 Session Events

​请求头

​路径参数

​查询参数

​示例请求

​示例响应

​响应字段

​Event 对象字段

​按类型允许的 payload 字段

​错误

​注意事项

​相关

发送 Session Events

订阅 Session Events

请求头

路径参数

查询参数

示例请求

示例响应

响应字段

Event 对象字段

按类型允许的 payload 字段

错误

注意事项

相关