Consume Session Events (SSE) - Archetype AI Documentation

Overview

This endpoint opens a Server-Sent Events stream for an active lens session. Output processors of type server_sent_events_writer (used by the Activity Monitor lens and most cookbook lenses) write inference results, log messages, and stream status events to this channel.

Lens sessions route outputs through one of two channels, never both:

SSE consumer (this endpoint) — for lenses whose model_pipeline includes a server_sent_events_writer output processor.
WebSocket mailbox — drained via session.read.

If session.read returns event_data: null while GET /lens/sessions/metadata shows non-zero num_outputs, the lens is writing to the SSE consumer — use this endpoint.The official archetypeai Python SDK exposes this endpoint as lens.create_sse_consumer(session_id).

Path Parameters

session_id

string

required

Identifier of the active session whose output stream to subscribe to. Returned by Create Lens Session.

Headers

Authorization

string

required

Bearer YOUR_API_KEY

string

text/event-stream (recommended — signals SSE intent to the server and to intermediaries)

Last-Event-ID

string

Optional cursor. When set, the server resumes the stream after the event with the given id, so reconnecting clients do not miss or duplicate messages. Matches the standard SSE reconnection semantic.

Response

The response is an text/event-stream HTTP response. Each frame is a standard SSE record:

event: message
id: <opaque cursor>
data: {"type": "<event.type>", ...}

The data: payload is JSON and always includes a type field identifying the event. The consumer emits three envelope event types in addition to lens-specific output events:

type=sse.stream.start

event

First frame emitted after the connection is established. Carries the session_id of the stream and a server-assigned reader_id that identifies this consumer connection.

{
  "type": "sse.stream.start",
  "event_data": {
    "session_id": "lsn-...",
    "reader_id": "<opaque>"
  }
}

type=sse.stream.heartbeat

event

Periodic keepalive frame used to hold the connection open through proxies and to surface session-side counters. message_timeout increments with each heartbeat — clients should ignore the payload contents but can use the frame as a liveness signal.

{
  "type": "sse.stream.heartbeat",
  "event_data": {
    "session_id": "lsn-...",
    "session_status": "SESSION_STATUS_RUNNING",
    "num_messages": 0,
    "num_bytes": 0,
    "message_timeout": 5.0
  }
}

type=sse.stream.end

event

The server is closing the stream gracefully (for example, the session was destroyed). Clients should stop consuming after receiving this event.

All other type values are lens-specific output events. Typical types emitted by server_sent_events_writer include inference.result, log.info, frame.processed, and error. The exact shape of the data payload depends on the lens’s model_pipeline and the processor that produced the event.

curl -N https://api.u1.archetypeai.app/v0.5/lens/sessions/consumer/lsn-250313c2177253cbaa7a73542edd90 \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Accept: text/event-stream"

event: message
data: {"type": "sse.stream.start", "event_data": {"session_id": "lsn-...", "reader_id": "87e6d51c992557bc"}}

event: message
data: {"type": "sse.stream.heartbeat", "event_data": {"session_id": "lsn-...", "session_status": "SESSION_STATUS_RUNNING", "num_messages": 0, "num_bytes": 0, "message_timeout": 5.0}}

event: message
data: {"type": "inference.result", "timestamp": 1741843200.123, "data": {"result": "A construction worker wearing a hard hat and safety vest"}}

event: message
data: {"type": "sse.stream.end"}

Choosing Between SSE and `session.read`

	SSE consumer (this endpoint)	`session.read`
Transport	HTTP `text/event-stream`	WebSocket event over `session_endpoint`
Pattern	Server pushes events as they arrive	Client polls; server returns queued messages
Used by	Lenses with `server_sent_events_writer` output processors	Lenses with mailbox-style output processors
Cursor / resume	`Last-Event-ID` request header	`client_id` field in `event_data`
Heartbeats	`sse.stream.heartbeat` envelope events	None (request/response pattern)
Graceful close	`sse.stream.end` envelope event, then HTTP close	Close WebSocket

Inspect the lens’s model_pipeline via GET /lens/metadata to see which output processor (and therefore which channel) it uses.

API Reference

Documentation Index

​Overview

​Path Parameters

​Headers

​Response

​Choosing Between SSE and session.read

Overview

Path Parameters

Headers

Response

Choosing Between SSE and `session.read`