Skip to main content

​
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

EventSchemaWhen it firesKey fields
statusStatusEventLifecycle changes (starting, processing, waiting_media, completed).phase, progress (0-1).
partial_transcriptPartialTranscriptEventOnly in live capture when interim text is available.partial_id, text, is_final.
final_transcriptFinalTranscriptEventAfter an utterance is finalized.utterance_id, speaker, t_start, t_end, text.
emotionEmotionEventImmediately after each final_transcript.emotion.emotions.*, scores (PAD), confidence.
cognitiveCognitiveEventMirrors emotion cadence.signals, engagement, cognitive_load.
transitionTransitionEventWhen significant state changes are detected.from_state, to_state, drivers.
momentMomentEventDetected objections, CTAs, and topic shifts.category, confidence, evidence.
summary_updateConversationSummaryOnce per conversation after processing completes.See Section 13 for schema.
errorErrorEventFatal 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.
​
phase
string
required
Current processing phase. One of: starting, processing, waiting_media, completed
​
progress
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.
​
partial_id
string
required
Unique identifier for this partial transcript
​
text
string
required
Partial transcript text
​
is_final
boolean
required
Whether this is a final transcript segment

​
Final Transcript Event

Fired per utterance once a segment is finalized.
​
utterance_id
string
required
Unique identifier for the utterance
​
speaker
string
required
Speaker identifier from diarization
​
text
string
required
Final transcript text
​
t_start
number
required
Start time in seconds
​
t_end
number
required
End time in seconds

​
Emotion Event

Emitted immediately after each final_transcript. Includes PAD scores (valence, arousal, dominance) and emotion classifications.
​
utterance_id
string
required
Associated utterance identifier
​
speaker_id
string
required
Speaker identifier
​
emotion
object
required
Emotion scores (e.g., {"joy": 0.64, "fear": 0.05, ...})
​
scores
object
required
PAD scores: valence, arousal, dominance (each 0-1)
​
confidence
number
required
Confidence score (0-1)
​
stability
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.
​
utterance_id
string
required
Associated utterance identifier
​
speaker_id
string
required
Speaker identifier
​
signals
object
required
Cognitive analysis signals
​
engagement
number
required
Engagement score (0-1)
​
cognitive_load
string
required
Cognitive load level

​
Transition Event

Triggers when significant state changes are detected.
​
transition_id
string
required
Unique transition identifier
​
at_ms
integer
required
Timestamp in milliseconds
​
from_state
object
required
Previous affective state
​
to_state
object
required
New affective state
​
drivers
object
required
Highlights which signals contributed to the transition
​
evidence_utterance_ids
array
required
Array of utterance IDs that contributed to this transition
​
confidence
number
required
Confidence score (0-1)

​
Moment Event

Detected objections, CTAs, and topic shifts.
​
moment_id
string
required
Unique moment identifier
​
category
string
required
Moment category: objection, cta_offered, cta_accepted, cta_rejected, topic_shift
​
speaker_id
string
required
Speaker identifier
​
start_ms
integer
required
Start timestamp in milliseconds
​
end_ms
integer
required
End timestamp in milliseconds
​
utterance_ids
array
required
Array of associated utterance IDs
​
summary
string
required
Summary of the moment
​
evidence
array
required
Evidence supporting the moment detection
​
confidence
number
required
Confidence score (0-1)

​
Summary Update Event

Emitted once per conversation after processing completes. Contains structured ConversationSummary.
​
summary
object
required
Full conversation summary object. See Response Schemas for complete schema.

​
Error Event

Fatal issues (ASR failure, invalid chunk, double SSE connection).
​
code
string
required
Error code. Notable codes: LIVE_ASR_FAILURE, NO_UTTERANCES, STREAM_FAILURE, INVALID_KEY, FILE_TOO_LARGE, ANALYSIS_FAILURE
​
message
string
required
Human-readable error message
Example: 
event: error
data: {"code":"STREAM_FAILURE","message":"Streaming connection lost"}

​
Done Event

Terminal success marker.
​
conversation_id
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:
  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.