curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1'
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=42&live=long-poll'
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1&live=sse'
Streams
Read stream
Read data from a stream using catch-up, long-poll, or SSE modes.
GET
/
ds
/
{bucket}
/
{stream}
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1'
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=42&live=long-poll'
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1&live=sse'
string
required
Bucket ID.
string
required
Stream ID within the bucket.
string
Starting offset. Use
-1 to read from the beginning, or a numeric offset.string
Opaque cursor token returned by a previous read. Alternative to
offset.string
Alias for
cursor.string
Live mode:
sse for Server-Sent Events, long-poll for long-polling. Omit for catch-up read.number
Maximum bytes to return in a single response (catch-up and long-poll only).
Read modes
- Catch-up
- Long-poll
- SSE
No
live parameter. Returns all available data from the given offset immediately.curl 'https://stream.tonbo.dev/ds/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 'https://stream.tonbo.dev/ds/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 'https://stream.tonbo.dev/ds/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). |
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 thedatafield. For binary streams, data is base64-encoded (controlled by theStream-Sse-Data-Encodingheader). - 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 'https://stream.tonbo.dev/ds/demo/hello?offset=-1'
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=42&live=long-poll'
curl 'https://stream.tonbo.dev/ds/demo/hello?offset=-1&live=sse'
See read modes, binary SSE, and offsets for more details.