> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# SSE Streaming

> Server-Sent Events provide real-time streaming of lens session output with automatic reader tracking and lifecycle management.

## SSE Stream Flow

```mermaid theme={"system"}
sequenceDiagram
    participant Client
    participant API
    participant Session
    
    Client->>API: Open SSE stream (reader_id)
    API->>Session: Register reader
    API->>Client: sse.stream.start
    
    loop While session active
        Session->>API: New event available
        API->>Client: Event data
    end
    
    loop No events (every 5s)
        API->>Client: sse.stream.heartbeat
    end
    
    Note over API,Client: After timeout or session killed
    API->>Client: sse.stream.end
    API->>Session: Unregister reader
```

***

## SSE Stream Characteristics

| Feature             | Behavior                                                              |
| ------------------- | --------------------------------------------------------------------- |
| **Reader Tracking** | Each reader gets unique `reader_id` for independent position tracking |
| **Heartbeats**      | Sent every 5 seconds when no data available                           |
| **Auto-Timeout**    | Stream closes automatically after extended inactivity                 |
| **Session TTL**     | Default 10 minutes (600 seconds)                                      |
| **Event Format**    | Standard SSE: `data: {json}\n\n`                                      |

***

## SSE Lifecycle Events

### sse.stream.start

Sent when SSE stream connection opens.

<CodeGroup>
  ```json sse.stream.start theme={"system"}
  {
    "type": "sse.stream.start",
    "event_data": {
      "session_id": "lsn-abc123",
      "reader_id": "reader_xyz"
    }
  }
  ```
</CodeGroup>

***

### sse.stream.heartbeat

Sent periodically when no data events are available.

<CodeGroup>
  ```json sse.stream.heartbeat theme={"system"}
  {
    "type": "sse.stream.heartbeat",
    "event_data": {
      "session_id": "lsn-abc123",
      "session_status": "SESSION_STATUS_RUNNING",
      "num_messages": 42,
      "num_bytes": 15234,
      "message_timeout": 2.5,
      "reader_id": "reader_xyz"
    }
  }
  ```
</CodeGroup>

***

### sse.stream.end

Sent when stream closes (timeout or session termination).

<CodeGroup>
  ```json Normal Close theme={"system"}
  {
    "type": "sse.stream.end",
    "event_data": {
      "session_id": "lsn-abc123",
      "session_status": "SESSION_STATUS_RUNNING",
      "num_messages": 100,
      "num_bytes": 45678,
      "message_timeout": 58.2,
      "reader_id": "reader_xyz"
    }
  }
  ```

  ```json Session Killed theme={"system"}
  {
    "type": "sse.stream.end",
    "event_data": {
      "session_id": "lsn-abc123",
      "reader_id": "reader_xyz",
      "session_status": "SESSION_STATUS_KILLED",
      "warning": "Session status is : SESSION_STATUS_KILLED"
    }
  }
  ```
</CodeGroup>

***

## SSE Reader Statistics

Each reader tracks the following metrics:

| Metric                  | Description                        |
| ----------------------- | ---------------------------------- |
| `num_messages`          | Total messages sent to this reader |
| `num_bytes`             | Total bytes transmitted            |
| `num_errors`            | Transmission errors encountered    |
| `stream_send_delay_sec` | 95th percentile send latency       |
| `sse_start_time`        | Stream start timestamp             |
| `sse_end_time`          | Stream end timestamp               |
| `sse_run_time`          | Total stream duration              |