Skip to main content
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 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

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

Headers

string
required
Bearer YOUR_API_KEY
string
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 an text/event-stream HTTP response. Each frame is a standard SSE record:
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:
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.
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.

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.