Skip to main content
GET
/
lens
/
sessions
/
consumer
/
{session_id}
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"}

​
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
​
Accept
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
TransportHTTP text/event-streamWebSocket event over session_endpoint
PatternServer pushes events as they arriveClient polls; server returns queued messages
Used byLenses with server_sent_events_writer output processorsLenses with mailbox-style output processors
Cursor / resumeLast-Event-ID request headerclient_id field in event_data
Heartbeatssse.stream.heartbeat envelope eventsNone (request/response pattern)
Graceful closesse.stream.end envelope event, then HTTP closeClose WebSocket
Inspect the lens’s model_pipeline via GET /lens/metadata to see which output processor (and therefore which channel) it uses.