订阅 Session Event Stream

GET /api/v1/forward/sessions/{session_id}/events/stream 以 Server-Sent Events 形式实时返回 Session 事件；data payload 与历史查询使用相同的 Forward 字段过滤模型。新接入如需流式输出，建议通过 event_deltas[] 订阅流式增量事件。

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT 或 SAT>`
Accept	是	`text/event-stream`
Last-Event-ID	否	从该 Event ID 之后恢复订阅。
X-Qoder-Beta	订阅 thinking 流式增量时	请求 `event_deltas[]=agent.thinking` 时，必须设置为 `thinking-event-stream-delta-2026-07-20`。

路径参数

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

查询参数

参数	类型	是否必填	默认值	说明
event_deltas[]	string	否	-	订阅指定公开事件类型的流式增量事件。支持重复传参，取值见 Session 与 Event 数据结构。
include_tool_calls	boolean	否	true	是否包含工具调用类事件。
include_thinking	boolean	否	true	是否包含思考过程事件。

示例请求

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions/sess_xxx/events/stream' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Accept: text/event-stream"

订阅文本和思考的流式增量事件（订阅 agent.thinking 需携带 Beta 请求头）：

curl -s -G 'https://api.qoder.com.cn/api/v1/forward/sessions/sess_xxx/events/stream' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Accept: text/event-stream" \
  -H "X-Qoder-Beta: thinking-event-stream-delta-2026-07-20" \
  --data-urlencode 'event_deltas[]=agent.message' \
  --data-urlencode 'event_deltas[]=agent.thinking'

示例响应

HTTP 200 OK

id: evt_xxx
event: agent.message
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"}

流式增量事件示例：

id: evt_xxx
event: event_start
data: {"id":"evt_xxx","type":"event_start","session_id":"sess_xxx","event":{"id":"evt_xxx","type":"agent.message"}}

id: evt_xxx
event: event_delta
data: {"id":"evt_xxx","type":"event_delta","session_id":"sess_xxx","event_id":"evt_xxx","delta":{"type":"content_delta","index":0,"content":{"type":"text","text":"Here"}}}

模型用量事件示例：

id: evt_xxx
event: span.model_request_end
data: {"id":"evt_xxx","type":"span.model_request_end","is_error":false,"model_request_start_id":"evt_yyy","model_usage":{"credits":0.42},"processed_at":"2026-06-22T11:00:01Z"}

响应字段

字段	类型	说明
id	string	SSE event ID，等于 Event ID。
event	string	Event 类型。
data	object	过滤后的 Forward Event JSON。普通公开事件的 payload 字段遵循 List Session Events 中按 Event `type` 分发的字段矩阵；流式增量事件见数据结构文档中的 `event_start` / `event_delta`。

连接中断与重连

SSE 连接可能因网关超时、服务端重启等原因断开，服务端不保证连接长期存活，客户端必须自行实现重连重试：

持续记录最后收到的 SSE frame 的 id（即 Event ID）。
断开后用 Last-Event-ID 请求头携带该 ID 重新订阅，从断点继续，避免漏收事件。
重连不带 Last-Event-ID 时，从建连时刻的事件流末尾开始，仅接收连接建立之后新产生的事件，不回放历史事件。如需补收断线期间的事件，请先通过列出 Session Events接口分页查询历史，再建立 SSE 连接续传。
自 2026-08-24 起，未携带 Last-Event-ID 建立连接时，服务端从建连时刻的事件流末尾开始推送，不回放历史事件。推荐接入方式：历史事件通过 List Events 分页获取，实时事件通过 SSE 接收，断线时携带最后收到的 Event ID 作为 Last-Event-ID 重连，并按 Event ID 做幂等处理。

错误

HTTP	Type	Code	触发条件
404	`not_found_error`	-	`Last-Event-ID` 对应的 Event 不存在或不属于当前 Session。
404	`not_found_error`	`session_not_found`	Session 不存在。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

event_deltas[] 是推荐的新流式开启方式；未传该参数时只返回普通公开事件。
agent.thinking 流式增量当前为 Beta 功能，订阅时必须携带请求头 X-Qoder-Beta: thinking-event-stream-delta-2026-07-20；Beta 期间的行为可能调整，请关注版本说明。
一次模型调用完成后会输出 span.model_request_end 模型用量事件，model_usage.credits 为单次调用增量；Session 累计用量请通过获取 Session 接口读取 usage.total_credits，字段见数据结构文档中的模型用量事件。
未知 Event 类型可用时会作为 envelope-only 事件转发。
include_thinking=false 会过滤 thinking 事件、旧版 thinking delta，以及新流式中的 agent.thinking 事件开始信号和 delta.content.type=thinking 的增量片段。
include_tool_calls=false 会过滤工具调用事件和旧版工具输入/输出 delta。

订阅 Session Event Stream

请求头

路径参数

查询参数

示例请求

示例响应

响应字段

连接中断与重连

错误

备注

相关

创建 Session

列出 Session Events

​请求头

​路径参数

​查询参数

​示例请求

​示例响应

​响应字段

​连接中断与重连

​错误

​备注

​相关

创建 Session

列出 Session Events

请求头

路径参数

查询参数

示例请求

示例响应

响应字段

连接中断与重连

错误

备注

相关