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

# Server-Sent Events (SSE)

> Real-time event reference for streaming endpoints

## Overview

Several endpoints return Server-Sent Events (SSE) streams for real-time updates during analysis.

## SSE Endpoints

The following endpoints support SSE streaming:

* `POST /analyze/stream` - Stream analysis events for uploaded media
* `POST /analyze?stream=true` - Alias for `/analyze/stream`
* `GET /analyze/live/{session_id}/events` - Subscribe to events for a live session

<Warning>
  Only one SSE consumer may be attached to a live session at a time. Attempting to attach a second listener will return `409 Conflict`.
</Warning>

## Event Catalogue

| Event                | Schema                   | When it fires                                                               | Key fields                                             |
| -------------------- | ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------ |
| `status`             | `StatusEvent`            | Lifecycle changes (`starting`, `processing`, `waiting_media`, `completed`). | `phase`, `progress` (0-1).                             |
| `partial_transcript` | `PartialTranscriptEvent` | Only in live capture when interim text is available.                        | `partial_id`, `text`, `is_final`.                      |
| `final_transcript`   | `FinalTranscriptEvent`   | After an utterance is finalized.                                            | `utterance_id`, `speaker`, `t_start`, `t_end`, `text`. |
| `emotion`            | `EmotionEvent`           | Immediately after each `final_transcript`.                                  | `emotion.emotions.*`, `scores` (PAD), `confidence`.    |
| `cognitive`          | `CognitiveEvent`         | Mirrors `emotion` cadence.                                                  | `signals`, `engagement`, `cognitive_load`.             |
| `transition`         | `TransitionEvent`        | When significant state changes are detected.                                | `from_state`, `to_state`, `drivers`.                   |
| `moment`             | `MomentEvent`            | Detected objections, CTAs, and topic shifts.                                | `category`, `confidence`, `evidence`.                  |
| `summary_update`     | `ConversationSummary`    | Once per conversation after processing completes.                           | See Section 13 for schema.                             |
| `error`              | `ErrorEvent`             | Fatal issues (ASR failure, invalid chunk, double SSE connection).           | `code`, `message`.                                     |
| `done`               | `{ conversation_id }`    | Terminal success marker.                                                    | `conversation_id`.                                     |

## Event Types

### Status Event

Emitted during processing to indicate current phase and progress.

<ParamField body="phase" type="string" required>
  Current processing phase. One of: `starting`, `processing`, `waiting_media`, `completed`
</ParamField>

<ParamField body="progress" type="number" required>
  Progress indicator from 0 to 1
</ParamField>

**Example:**

```
event: status
data: {"phase":"processing","progress":0.45}
```

### Partial Transcript Event

Arrives only in live capture when interim text is available.

<ParamField body="partial_id" type="string" required>
  Unique identifier for this partial transcript
</ParamField>

<ParamField body="text" type="string" required>
  Partial transcript text
</ParamField>

<ParamField body="is_final" type="boolean" required>
  Whether this is a final transcript segment
</ParamField>

### Final Transcript Event

Fired per utterance once a segment is finalized.

<ParamField body="utterance_id" type="string" required>
  Unique identifier for the utterance
</ParamField>

<ParamField body="speaker" type="string" required>
  Speaker identifier from diarization
</ParamField>

<ParamField body="text" type="string" required>
  Final transcript text
</ParamField>

<ParamField body="t_start" type="number" required>
  Start time in seconds
</ParamField>

<ParamField body="t_end" type="number" required>
  End time in seconds
</ParamField>

### Emotion Event

Emitted immediately after each `final_transcript`. Includes PAD scores (valence, arousal, dominance) and emotion classifications.

<ParamField body="utterance_id" type="string" required>
  Associated utterance identifier
</ParamField>

<ParamField body="speaker_id" type="string" required>
  Speaker identifier
</ParamField>

<ParamField body="emotion" type="object" required>
  Emotion scores (e.g., `{"joy": 0.64, "fear": 0.05, ...}`)
</ParamField>

<ParamField body="scores" type="object" required>
  PAD scores: `valence`, `arousal`, `dominance` (each 0-1)
</ParamField>

<ParamField body="confidence" type="number" required>
  Confidence score (0-1)
</ParamField>

<ParamField body="stability" type="string" required>
  Stability indicator (e.g., `"final"`)
</ParamField>

**Example:**

```
event: emotion
data: {
  "utterance_id": "analysis_1234_utt_0007",
  "speaker_id": "Speaker_1",
  "emotion": {"joy":0.64,"fear":0.05,...},
  "scores": {"valence":0.41,"arousal":0.58,"dominance":0.52},
  "confidence":0.78,
  "stability":"final"
}
```

### Cognitive Event

Mirrors `emotion` cadence. Includes engagement and cognitive load analysis.

<ParamField body="utterance_id" type="string" required>
  Associated utterance identifier
</ParamField>

<ParamField body="speaker_id" type="string" required>
  Speaker identifier
</ParamField>

<ParamField body="signals" type="object" required>
  Cognitive analysis signals
</ParamField>

<ParamField body="engagement" type="number" required>
  Engagement score (0-1)
</ParamField>

<ParamField body="cognitive_load" type="string" required>
  Cognitive load level
</ParamField>

### Transition Event

Triggers when significant state changes are detected.

<ParamField body="transition_id" type="string" required>
  Unique transition identifier
</ParamField>

<ParamField body="at_ms" type="integer" required>
  Timestamp in milliseconds
</ParamField>

<ParamField body="from_state" type="object" required>
  Previous affective state
</ParamField>

<ParamField body="to_state" type="object" required>
  New affective state
</ParamField>

<ParamField body="drivers" type="object" required>
  Highlights which signals contributed to the transition
</ParamField>

<ParamField body="evidence_utterance_ids" type="array" required>
  Array of utterance IDs that contributed to this transition
</ParamField>

<ParamField body="confidence" type="number" required>
  Confidence score (0-1)
</ParamField>

### Moment Event

Detected objections, CTAs, and topic shifts.

<ParamField body="moment_id" type="string" required>
  Unique moment identifier
</ParamField>

<ParamField body="category" type="string" required>
  Moment category: `objection`, `cta_offered`, `cta_accepted`, `cta_rejected`, `topic_shift`
</ParamField>

<ParamField body="speaker_id" type="string" required>
  Speaker identifier
</ParamField>

<ParamField body="start_ms" type="integer" required>
  Start timestamp in milliseconds
</ParamField>

<ParamField body="end_ms" type="integer" required>
  End timestamp in milliseconds
</ParamField>

<ParamField body="utterance_ids" type="array" required>
  Array of associated utterance IDs
</ParamField>

<ParamField body="summary" type="string" required>
  Summary of the moment
</ParamField>

<ParamField body="evidence" type="array" required>
  Evidence supporting the moment detection
</ParamField>

<ParamField body="confidence" type="number" required>
  Confidence score (0-1)
</ParamField>

### Summary Update Event

Emitted once per conversation after processing completes. Contains structured `ConversationSummary`.

<ParamField body="summary" type="object" required>
  Full conversation summary object. See [Response Schemas](/api-reference/response-schemas) for complete schema.
</ParamField>

### Error Event

Fatal issues (ASR failure, invalid chunk, double SSE connection).

<ParamField body="code" type="string" required>
  Error code. Notable codes: `LIVE_ASR_FAILURE`, `NO_UTTERANCES`, `STREAM_FAILURE`, `INVALID_KEY`, `FILE_TOO_LARGE`, `ANALYSIS_FAILURE`
</ParamField>

<ParamField body="message" type="string" required>
  Human-readable error message
</ParamField>

**Example:**

```
event: error
data: {"code":"STREAM_FAILURE","message":"Streaming connection lost"}
```

### Done Event

Terminal success marker.

<ParamField body="conversation_id" type="string" required>
  Final conversation identifier
</ParamField>

**Example:**

```
event: done
data: {"conversation_id":"analysis_f38de2c0c1"}
```

## SSE Format

SSE events follow the standard format:

```
event: <event_type>
data: <json_payload>

```

Multiple data lines are concatenated. Empty lines separate events.

## Event Order

Events are emitted in order:

1. `status` (`phase=start`)
2. `final_transcript` (per utterance once finalized)
3. For each utterance: `emotion`, `cognitive`, optional `transition` / `moment`
4. `summary_update` after the timeline completes
5. `status` (`phase=completed`)
6. `done`

## Error Handling

SSE streams may emit error events at any time. Clients should handle these gracefully:

* `LIVE_ASR_FAILURE`: Live ASR connection failed
* `NO_UTTERANCES`: No speech detected in media
* `STREAM_FAILURE`: General streaming failure
* `INVALID_KEY`: Missing/incorrect API key
* `FILE_TOO_LARGE`: Exceeded file size limit
* `ANALYSIS_FAILURE`: Downstream processing failure

Upon receiving an error event, the stream will typically close. The `done` event indicates successful completion.