Read stream

Read data from a stream using catch-up, long-poll, or SSE modes.

bucketpathstringrequired

Bucket ID.

streampathstringrequired

Stream ID within the bucket.

offsetquerystring

Starting offset. Use -1 to read from the beginning, or a numeric offset.

cursorquerystring

Opaque cursor token returned by a previous read. Alternative to offset.

stream-cursorquerystring

Alias for cursor.

livequerystring

Live mode: sse for Server-Sent Events, long-poll for long-polling. Omit for catch-up read.

max-bytesquerynumber

Maximum bytes to return in a single response (catch-up and long-poll only).

Read modes

No live parameter. Returns all available data from the given offset immediately.

curl 'http://127.0.0.1:4437/demo/hello?offset=-1'

live=long-poll. Returns immediately if data is available, otherwise holds the connection until new data arrives or a ~3 second timeout.

curl 'http://127.0.0.1:4437/demo/hello?offset=42&live=long-poll'

live=sse. Opens a persistent Server-Sent Events connection. The server pushes data events as new entries are appended. Includes periodic heartbeat comments.

curl 'http://127.0.0.1:4437/demo/hello?offset=-1&live=sse'

Response

Status	Meaning
`200`	Data returned (catch-up or long-poll with data).
`204`	No new data at the requested offset (catch-up only).
`400`	Invalid offset or live mode.
`404`	Stream not found or expired.
`410`	Requested offset has been trimmed (data no longer available).

Response headers include Stream-Next-Offset, Stream-Cursor, ETag, Stream-Up-To-Date, Stream-Closed, and Content-Type.

SSE event format

In SSE mode, the server sends:

Data events (event: data): stream payload in the data field. For binary streams, data is base64-encoded (controlled by the Stream-Sse-Data-Encoding header).
Control events (event: control): JSON metadata including the current offset and stream state.
Heartbeat comments: periodic : lines to keep the connection alive through proxies.

curl 'http://127.0.0.1:4437/demo/hello?offset=-1'

curl 'http://127.0.0.1:4437/demo/hello?offset=42&live=long-poll'

curl 'http://127.0.0.1:4437/demo/hello?offset=-1&live=sse'

See read modes, binary SSE, and offsets for more details.