> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询 Event 历史

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

`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 | 是否包含思考过程事件。          |

## 示例请求

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/events' \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "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 等运行时私有字段。

## 相关

<CardGroup cols={2}>
  <Card title="发送 Session Events" icon="paper-plane" href="/cloud-agents/api/forward/sessions/send-events" />

  <Card title="订阅 Session Events" icon="radio" href="/cloud-agents/api/forward/sessions/stream-events" />
</CardGroup>