Stream prospect items

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

Uses Server-Sent Events to deliver Webset state, criteria, search strategy, and item changes. Requires websets:read. Opening the stream does not start discovery or consume credits.

Connect

First fetch an Items snapshot, then pass its checkpoint as a pair:

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"

Parameter	Description
`cursor`	Snapshot `stream_cursor`; it may instead be sent as `Last-Event-ID`.
`items_revision`	Snapshot `items_revision`.
`match`	Same filter as the Items endpoint; defaults to `qualified`.

cursor and items_revision must both be present or both absent. If the URL cursor and Last-Event-ID are both present, they must match. Without a checkpoint, the stream starts at the latest event and only sends future changes.

Native browser EventSource cannot set a Bearer header. Use a streaming fetch client in browsers.

Events

`ready`

Connection metadata, current state, checkpoint, heartbeat_ms=15000, and max_stream_ms=240000.

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`

Sent when public Webset status changes. Includes webset_status, items_revision, and stream_cursor.

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

`webset.strategy`

A complete display snapshot sent when criteria or strategy changes. Its fields match the strategy endpoint.

`items.changed`

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

Upsert by item id and delete every removed_ids entry.
The SSE id becomes the new stream_cursor.
One revision may contain multiple chunks.
Commit items_revision only when chunk_index + 1 === chunk_count.
upserts use the compact item shape. Fetch REST Items when payload_truncated=true.

`reset`

The reason is cursor_expired, revision_gap, or revision_ahead. Stop applying that stream, replace local state with a complete snapshot, and reconnect from its checkpoint.

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

`complete`

The terminal state and final item changes were delivered. The server closes the stream. Do not close early solely because webset.state=completed.

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

`reconnect`

A connection lasts about four minutes. Reconnect immediately with the event's cursor + items_revision.

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

`error`

A post-connect read failure with code=stream_failed and a request_id. Back off and reconnect from the last complete checkpoint.

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

Heartbeats are : heartbeat ... SSE comments, not business events.

Concurrency and recovery

Default limits are two streams per API key, five per user, and three per Webset. Excess connections return 429 sse_connection_limit_exceeded. Events are retained for 24 hours; REST Items remain the source of truth.