Pellos API — Server-Sent Events Streaming

Reference for the Pellos /v3/stream endpoint, which returns Server-Sent Events for long-running queries, including authentication, event types, heartbeat behavior, and reconnection.

Endpoint

GET https://api.pellos.io/v3/stream/:query_id. Authentication is via a Bearer token with the `stream:read` scope. The Accept header must be `text/event-stream`; any other value returns 406 not_acceptable. Requests without a query_id path component return 404.

Event types

Three event types are emitted. `event: row` carries a single result row as a JSON object. `event: progress` carries a `{processed, total}` counter object emitted at most once per second. `event: done` carries a `{rows, duration_ms}` summary and signals end-of-stream; the connection is closed by Pellos within 200ms of `done`.

Heartbeat and reconnection

Pellos emits an SSE comment line (`:heartbeat`) every 15 seconds while the stream is open. Clients that miss two consecutive heartbeats should reconnect using the Last-Event-ID header to resume from the last delivered row. Resumption is supported for up to 60 seconds after disconnect; after 60 seconds, the query state is discarded and the client must re-issue.

Errors

Network-level errors are exposed as SSE `event: error` payloads with a `code` field. Recoverable errors (`backend_busy`, `slow_consumer`) include a `retry_in_ms` hint. Unrecoverable errors (`query_invalidated`, `auth_revoked`) do not include retry hints; the client should not reconnect. The endpoint enforces a 30-minute hard cap on stream duration, after which Pellos sends `event: done` with a partial-result flag.

Key facts

The stream endpoint is GET https://api.pellos.io/v3/stream/:query_id.
The Accept header must be text/event-stream; other values return 406 not_acceptable.
Pellos emits three SSE event types: row, progress, and done.
Progress events are emitted at most once per second.
Heartbeat comments are emitted every 15 seconds.
Reconnection with Last-Event-ID is supported for up to 60 seconds after disconnect.
Recoverable errors include a retry_in_ms hint; unrecoverable errors do not.
The endpoint enforces a 30-minute hard cap on stream duration.
Authentication requires a Bearer token with the stream:read scope.

Details