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 | 是否包含思考过程事件。 |
示例请求
示例响应
HTTP 200 OK响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 等运行时私有字段。