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.
Read the stream
Section titled “Read the stream”The stream is standard Server-Sent Events.
curl -s -N "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events/stream?after_seq=0" \ -H "Authorization: Bearer $SESSION_TOKEN"import jsonimport urllib.request
BASE = "https://agents.lumalabs.ai/v1"
request = urllib.request.Request( f"{BASE}/sessions/{session_id}/events/stream?after_seq=0", headers={"Authorization": f"Bearer {session_token}"},)with urllib.request.urlopen(request) as stream: for raw in stream: line = raw.decode().strip() if not line.startswith("data:"): continue event = json.loads(line[5:]) print(event.get("seq"), event.get("type")) if event.get("type") == "session.status_terminated": breakconst BASE = "https://agents.lumalabs.ai/v1";
const stream = await fetch( `${BASE}/sessions/${sessionId}/events/stream?after_seq=0`, { headers: { Authorization: `Bearer ${sessionToken}` }, },);const reader = stream.body!.pipeThrough(new TextDecoderStream()).getReader();let buffer = "";read: while (true) { const { value, done } = await reader.read(); if (done) break; buffer += value; const lines = buffer.split("\n"); buffer = lines.pop()!; for (const line of lines) { if (!line.startsWith("data:")) continue; const event = JSON.parse(line.slice(5)); console.log(event.seq, event.type); if (event.type === "session.status_terminated") break read; }}await reader.cancel();event: connecteddata: {"session_id": "72f946da-918a-454d-ae69-fe4740080e98", "head_seq": 18}
id: 1event: messagedata: {"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.
In a browser
Section titled “In a browser”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.
Resume after a drop
Section titled “Resume after a drop”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.
- Store the
seqof the last event you finished handling. Advance it only after handling succeeds, so a failed event is replayed. - On a drop, reconnect with that
seqasafter_seq. Skip any event whoseseqis not above it. - Stop when you see
session.status_terminated. That is the only time the stream ends.session.status_idledoes 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”.
- Approvals and review: answer what a session is waiting on.