Skip to content
Going further

Streaming

Follow a session's event log live and catch up after a drop.

A session has one event log. You read it on the stream or page through it. Everything you send goes through one route; its rules are in the Reference.

The stream is standard Server-Sent Events.

Terminal window
curl -s -N "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events/stream?after_seq=0" \
-H "Authorization: Bearer $SESSION_TOKEN"
event: connected
data: {"session_id": "72f946da-918a-454d-ae69-fe4740080e98", "head_seq": 18}
id: 1
event: message
data: {"type": "user.message", "content": "Make a square image of our sourdough loaf on a rustic table, morning light.", "id": "sevt_emsbs", "seq": 1, "direction": "in", "created_at": "2026-11-15T02:43:47.720517+00:00", "run_id": "e2089f1e-5333-4eb1-985e-6ca88f3adb04"}

These are the first frames of the Quickstart session, replayed after its turn had finished: head_seq is the newest seq on the log when you connect.

Each event arrives as event: message, with its JSON on the data: line and its seq on the id: line. Ignore the connected frame, the ping sent every 30 seconds, and comment lines starting with :.

Without a cursor, the stream starts at the live tail and you only see what happens after you connect. To start earlier, pass ?after_seq=<seq> or the standard Last-Event-ID header. after_seq=0 replays the whole session, so you can send a message before opening the stream and still see its first events.

Follow the stream instead of polling GET /v1/sessions/$SESSION_ID. Every session call counts against one per-minute limit per API client; see Errors.

Read the stream with fetch so the token stays in a header. The built-in EventSource can’t set headers.

For EventSource, mint a single-use stream token with POST /v1/sessions/$SESSION_ID/events/token (valid 60 seconds), pass it as ?token=, and on any error close the source and reconnect with a fresh token and your own cursor. Only give a browser a session token minted with a tenant_id; see Workspaces and access.

From a cursor, the stream replays every recorded event after that seq, then continues live. The seq values go up by exactly one, so nothing is skipped and nothing arrives twice. There is no replay window: you can resume from any seq for the life of the session.

  1. Store the seq of the last event you finished handling. Advance it only after handling succeeds, so a failed event is replayed.
  2. On a drop, reconnect with that seq as after_seq. Skip any event whose seq is not above it.
  3. Stop when you see session.status_terminated. That is the only time the stream ends. session.status_idle does not end it.

A reconnect with an expired session token is refused with 401, so mint a fresh one before the old one runs out. If the connection closes without session.status_terminated, read the snapshot before reconnecting. A status of terminated means no end event will follow.

To render history first, page through GET /v1/sessions/$SESSION_ID/events?after_seq=0&limit=100, following next_after_seq until has_more is false. Then open the stream with after_seq set to the last next_after_seq. The page is the full record of the session, so it answers “what happened while I was away”.