Live event stream (SSE)
const url = 'https://example.com/api/v1/events';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/api/v1/eventsServer-Sent Events stream of live job, sync, canary and drift progress.
Framing: the stream opens with retry: 5000, then emits data: <LiveEvent JSON> frames (see
#/components/schemas/LiveEvent). The first frame is always hello. Domain events
(job.*, sync.recorded, canary.updated, drift.updated) carry id: <bootId>-<seq>;
hello, resync and session.expired carry no id. A : ping comment is sent every 20 s.
Replay: send the last received id in the Last-Event-ID header (set automatically by
EventSource on reconnect) or the lastEventId query parameter. Missed domain events are
replayed from a 256-event in-memory buffer, at most 61 events per connection. When replay is
impossible the server sends resync and the client must refetch its state: reason: boot
when the id is from a previous server process or is over-long or malformed; reason: gap
when the id is older than the buffer or the backlog exceeds 61 events.
Session checks: each heartbeat re-validates the session or API token; when it is no longer
valid the server sends session.expired and closes the stream. Streams are closed after a
maximum lifetime of 60 minutes; clients reconnect and resume via Last-Event-ID.
Authentication: browser session cookie, or an API token with the read scope. Prefer the
X-Api-Key header; the ?apikey= query parameter is accepted for EventSource clients that
cannot set headers, but leaks into logs and history.
Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Praxrr API token (prx_…) with the read scope. Preferred over the apikey query
parameter.
Id of the last domain event the client received (<bootId>-<seq>), for replay.
Query Parameters
Section titled “Query Parameters”Praxrr API token with the read scope, for EventSource clients that cannot set headers.
Warning: the token leaks into proxy and access logs and browser history; prefer
X-Api-Key.
Query-string alternative to the Last-Event-ID header.
Responses
Section titled “Responses”text/event-stream of LiveEvent frames. Each data: line is a JSON
#/components/schemas/LiveEvent.
Unauthenticated (no valid session, or missing, invalid, revoked, or expired API token).
object
Error message
Stable machine-readable code present on 5xx responses; error is a fixed user-safe message, raw detail is logged server-side only
Example
{ "code": "cleanup_failed"}The API token lacks the read scope.
An authenticated API token lacks the scope the requested route requires.
object
Always Forbidden.
The API token scope this request requires.
Example
{ "requiredScope": "read"}Too many concurrent streams for this principal.
object
Error message
Stable machine-readable code present on 5xx responses; error is a fixed user-safe message, raw detail is logged server-side only
Example
{ "code": "cleanup_failed"}Headers
Section titled “Headers”The server-wide stream limit is reached.
object
Error message
Stable machine-readable code present on 5xx responses; error is a fixed user-safe message, raw detail is logged server-side only
Example
{ "code": "cleanup_failed"}