实时订阅潜客结果

GET/api/v2/websets/{webset_id}/items/stream

通过 Server-Sent Events 接收 Webset 状态、挖掘条件、搜索策略和 Item 增量。需要 websets:read 权限；连接不启动搜索，也不扣积分。

建立连接

应先读取 Items 快照，再把 checkpoint 成对传入：

cURL
curl -N "https://revor.ai/api/v2/websets/WEBSET_ID/items/stream?cursor=289&items_revision=18&match=qualified"   -H "Authorization: Bearer sk-revor-REPLACE_ME"   -H "Accept: text/event-stream"

参数	说明
`cursor`	快照的 `stream_cursor`；也可使用 `Last-Event-ID` header。
`items_revision`	快照的 `items_revision`。
`match`	与 Items 接口相同，默认 `qualified`。

cursor 与 items_revision 必须同时提供或同时省略。URL cursor 和 Last-Event-ID 同时存在时必须相等。不传 checkpoint 会从连接时的最新位置开始，只接收之后的变化。

浏览器原生 EventSource 不能设置 Bearer header，请使用支持流式响应的 fetch 客户端。

事件

`ready`

JSON
{
  "webset_id": "webset-uuid",
  "request_id": "req_xxx",
  "items_revision": 18,
  "latest_items_revision": 18,
  "stream_cursor": 289,
  "webset_status": "verifying",
  "heartbeat_ms": 15000,
  "max_stream_ms": 240000
}

`webset.state`

JSON
{
  "webset_id": "webset-uuid",
  "webset_status": "completed",
  "items_revision": 21,
  "stream_cursor": 292
}

`webset.strategy`

条件或策略发生变化时发送完整可展示快照，字段与策略接口一致。

`items.changed`

Text
id: 290
event: items.changed
data: {"webset_id":"...","items_revision":19,"chunk_index":0,"chunk_count":1,"upserts":[...],"removed_ids":[]}

按 Item id 应用 upserts，删除 removed_ids。
SSE id 是新的 stream_cursor。
一个 revision 可能拆成多个 chunk。
仅在 chunk_index + 1 === chunk_count 时提交新的 items_revision。
upserts 使用 compact Item 结构；payload_truncated=true 时通过 REST 获取完整数据。

`reset`

JSON
{
  "webset_id": "webset-uuid",
  "reason": "revision_gap",
  "items_revision": 21,
  "stream_cursor": 292
}

原因可能为 cursor_expired、revision_gap 或 revision_ahead。停止应用当前增量，重新读取完整快照并用新 checkpoint 建流。

`complete`

JSON
{
  "webset_id": "webset-uuid",
  "webset_status": "completed",
  "items_revision": 21,
  "stream_cursor": 292
}

终态和最后一批变更都已发送，服务端随后关闭连接。不要仅因 webset.state=completed 自行提前关闭。

`reconnect`

JSON
{
  "webset_id": "webset-uuid",
  "cursor": 292,
  "items_revision": 21
}

单条连接最长约四分钟。使用事件给出的 checkpoint 立即重连。

`error`

JSON
{
  "webset_id": "webset-uuid",
  "code": "stream_failed",
  "request_id": "req_xxx"
}

使用最后完整 checkpoint 退避重连。心跳是 : heartbeat ... SSE 注释，不是业务事件。

并发与恢复

默认上限为单 API Key 2 条、单用户 5 条、同一 Webset 3 条。超限返回 429 sse_connection_limit_exceeded。事件短期保留 24 小时；REST Items 始终是权威数据源。