Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt

Use this file to discover all available pages before exploring further.

Streaming endpoints deliver events as they happen, using Server-Sent Events (SSE).

​
Subscribe to a session

GET /v1/sessions/{id}/events/stream
Authorization: Bearer nsk_live_...
Accept: text/event-stream
Wire format: 
event: click
id: evt_01HZ...
data: {"t_ms": 12480, "payload": { ... }, "frame_id": "frm_01HZ..."}

event: validation_error
id: evt_01HZ...
data: {"t_ms": 13_900, "payload": { "field": "vendor" }}

: keepalive
The : keepalive comment fires every 15 seconds to keep proxies from idling out the connection.

​
Filter the stream

Server-side filters reduce bandwidth: 
GET /v1/sessions/{id}/events/stream?type=click&type=validation_error
ParamNotes
typeRepeat for multiple.
confidence_gteDrop low-confidence events.
from_t_msOnly events at or after this offset (useful for back-fill).

​
Subscribing to all sessions of a workflow

GET /v1/workflows/process_invoice/events/stream
Emits events for every active session of the workflow, in the same SSE format with an extra session_id field on each event.

​
Resumption

If your connection drops, resume with Last-Event-ID: 
Last-Event-ID: evt_01HZ...
The server replays any events you missed since that id, then continues live. The replay window is 30 minutes — older events must be fetched via the non-streaming endpoint.

​
SDK helpers

The TypeScript and Python SDKs expose events.stream() which handles reconnection, Last-Event-ID, and parsing automatically: 
for await (const ev of nusomi.events.stream(sessionId)) {
  console.log(ev.type, ev.t_ms);
}

​
WebSocket alternative

For environments where SSE is awkward (browsers behind specific proxies, embedded clients), Nusomi also exposes a WebSocket endpoint with the same filtering semantics: 
wss://api.nusomi.com/v1/sessions/{id}/events/ws
Authorization-Token: nsk_live_...
The wire frame is {"type": "click", "id": "evt_...", "data": {...}}. WebSocket is at parity with SSE but slightly higher overhead per session — prefer SSE unless you specifically need bidirectional traffic (e.g. server-driven cancel).

​
Concurrency

Each API key has a default concurrent-stream limit (50 streams per key, 500 per workspace). Streams beyond the limit get 429 stream_limit_exceeded.

​
Backpressure

If your consumer falls behind, Nusomi buffers up to 30 seconds of events per stream then starts dropping the oldest. A : dropped <n> comment is emitted whenever drops happen so your client can tell. To avoid this: process events asynchronously and offload heavy work to a queue.