Lens API
Consume Session Events (SSE)
Subscribe to a lens session’s Server-Sent Events stream to receive asynchronous inference results
GET
Requires version 1.1.5 or later of the Archetype platform.
Overview
This endpoint opens a Server-Sent Events stream for an active lens session. Output processors of typeserver_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_pipelineincludes aserver_sent_events_writeroutput processor. - WebSocket mailbox — drained via
session.read.
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
string
required
Identifier of the active session whose output stream to subscribe to. Returned by Create Lens Session.
Headers
string
required
Bearer YOUR_API_KEYstring
text/event-stream (recommended — signals SSE intent to the server and to intermediaries)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 antext/event-stream HTTP response. Each frame is a standard SSE record:
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:
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.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.event
The server is closing the stream gracefully (for example, the session was destroyed). Clients should stop consuming after receiving this event.
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.
Choosing Between SSE and session.read
Inspect the lens’s
model_pipeline via GET /lens/metadata to see which output processor (and therefore which channel) it uses.