Server-Sent Events (SSE)

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

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

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.

string

required

Current processing phase. One of: starting, processing, waiting_media, completed

number

required

Progress indicator from 0 to 1

Example:

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

Partial Transcript Event

Arrives only in live capture when interim text is available.

string

required

Unique identifier for this partial transcript

string

required

Partial transcript text

boolean

required

Whether this is a final transcript segment

Final Transcript Event

Fired per utterance once a segment is finalized.

string

required

Unique identifier for the utterance

string

required

Speaker identifier from diarization

string

required

Final transcript text

number

required

Start time in seconds

number

required

End time in seconds

Emotion Event

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

string

required

Associated utterance identifier

string

required

Speaker identifier

object

required

Emotion scores (e.g., {"joy": 0.64, "fear": 0.05, ...})

object

required

PAD scores: valence, arousal, dominance (each 0-1)

number

required

Confidence score (0-1)

string

required

Stability indicator (e.g., "final")

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.

string

required

Associated utterance identifier

string

required

Speaker identifier

object

required

Cognitive analysis signals

number

required

Engagement score (0-1)

string

required

Cognitive load level

Transition Event

Triggers when significant state changes are detected.

string

required

Unique transition identifier

integer

required

Timestamp in milliseconds

object

required

Previous affective state

object

required

New affective state

object

required

Highlights which signals contributed to the transition

array

required

Array of utterance IDs that contributed to this transition

number

required

Confidence score (0-1)

Moment Event

Detected objections, CTAs, and topic shifts.

string

required

Unique moment identifier

string

required

Moment category: objection, cta_offered, cta_accepted, cta_rejected, topic_shift

string

required

Speaker identifier

integer

required

Start timestamp in milliseconds

integer

required

End timestamp in milliseconds

array

required

Array of associated utterance IDs

string

required

Summary of the moment

array

required

Evidence supporting the moment detection

number

required

Confidence score (0-1)

Summary Update Event

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

object

required

Full conversation summary object. See Response Schemas for complete schema.

Error Event

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

string

required

Error code. Notable codes: LIVE_ASR_FAILURE, NO_UTTERANCES, STREAM_FAILURE, INVALID_KEY, FILE_TOO_LARGE, ANALYSIS_FAILURE

string

required

Human-readable error message

Example:

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

Done Event

Terminal success marker.

string

required

Final conversation identifier

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:

status (phase=start)
final_transcript (per utterance once finalized)
For each utterance: emotion, cognitive, optional transition / moment
summary_update after the timeline completes
status (phase=completed)
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.

Introduction

Endpoints

Cookbooks

Reference

Overview

SSE Endpoints

Event Catalogue

Event Types

Status Event

Partial Transcript Event

Final Transcript Event

Emotion Event

Cognitive Event

Transition Event

Moment Event

Summary Update Event

Error Event

Done Event

SSE Format

Event Order

Error Handling

​Overview

​SSE Endpoints

​Event Catalogue

​Event Types

​Status Event

​Partial Transcript Event

​Final Transcript Event

​Emotion Event

​Cognitive Event

​Transition Event

​Moment Event

​Summary Update Event

​Error Event

​Done Event

​SSE Format

​Event Order

​Error Handling

Overview

SSE Endpoints

Event Catalogue

Event Types

Status Event

Partial Transcript Event

Final Transcript Event

Emotion Event

Cognitive Event

Transition Event

Moment Event

Summary Update Event

Error Event

Done Event

SSE Format

Event Order

Error Handling