Stream

Streaming (SSE)

Open the Server-Sent Events connection, pass the right query parameters, handle each event type, and reconnect cleanly without missing matches.

View as Markdown

GET /v1/stream?timeout=60&since=30m&limit=100

Opens a Server-Sent Events connection authenticated with a tap token. Only events matching the tap's rules are delivered.

curl -N https://api.firehose.com/v1/stream \
  -H "Authorization: Bearer $FIREHOSE_TAP_TOKEN"

Query parameters

Parameter	Type	Description
`timeout`	int	Connection duration in seconds, 1–300. Default 300
`since`	string	Replay buffered events from a relative window, e.g. `5m`, `1h`, `24h` (max 24h)
`offset`	int	Start from an exact event offset on the tap's stream
`limit`	int	Close after delivering this many events, 1–10000

Buffered events are retained for roughly 24 hours.

Precedence: Last-Event-ID > offset > since > live tail.

Event types

A connected event is sent on open:

event: connected
data: {}

An update event is a page that matched a rule:

id: 0-43368
event: update
data: {"query_ids":["1"],"matched_at":"2026-02-13T08:06:32Z","tap_id":"1","document":{"url":"https://example.com/page","title":"Example Page","diff":{"chunks":[{"typ":"ins","text":"…"}]}}}

An error event reports a problem:

event: error
data: {"message":"No rules configured. Create rules first via POST /v1/rules."}

An end event means the stream closed normally (timeout or limit). Reconnect to continue:

event: end
data: {}

Each update carries an id:. Send it back as the Last-Event-ID header to resume from the next event. The browser EventSource API does this automatically on reconnect, so a dropped connection resumes where it left off (within the ~24h buffer).

The native browser EventSource API cannot send custom headers, so it can't pass the Authorization bearer token. You'll need an SSE client that supports request headers — see code examples.

See Match payload for every field on the delivered document.

Next steps

Code examples

Working SSE clients in curl, Node, and Python.

Stream disconnects or errors