Events the server pushes over the WebSocket connection.
Overview
| type | Source | Description |
|---|---|---|
| session.created | Gateway | Sent on connection establishment |
| session.updated | Upstream | Confirms session parameter update |
| input_audio_buffer.speech_started | Upstream | Speech segment detected |
| input_audio_buffer.speech_stopped | Upstream | Speech segment ended |
| conversation.item.input_audio_transcription.completed | Upstream | A speech segment has been transcribed (primary output) |
| lanson.throttled | Gateway | Throttle notification (max once per second) |
| error | Gateway / upstream | Error event |
session.created
Sent by the gateway immediately after connection.
{
"type": "session.created",
"request_id": "...",
"session_id": "sess_...",
"audio": { "format": "pcm_s16le", "sample_rate": 16000, "channels": 1 },
"turn_detection": { "type": "server_vad" },
"plan": "free",
"limits": {
"max_concurrent_utterances": 2,
"max_session_seconds": 900,
"idle_timeout_seconds": 60,
"remaining_audio_seconds": 3600
}
}
| Field | Type | Description |
|---|---|---|
| session_id | string | Session identifier |
| audio.format | string | Fixed: pcm_s16le |
| audio.sample_rate | number | Fixed: 16000 |
| audio.channels | number | Fixed: 1 |
| turn_detection.type | string | Fixed: server_vad |
| plan | string | Current plan |
| limits.max_concurrent_utterances | number | Max concurrent utterances |
| limits.max_session_seconds | number | Max session duration (seconds) |
| limits.idle_timeout_seconds | number | Idle timeout (seconds) |
| limits.remaining_audio_seconds | number \| null | Remaining audio budget (null when unlimited) |
session.updated
Confirms that a session.update message has taken effect.
{
"type": "session.updated",
"request_id": "...",
"language": "zh",
"turn_detection": { "type": "server_vad" }
}
input_audio_buffer.speech_started
VAD detected the start of a speech segment.
{
"type": "input_audio_buffer.speech_started",
"request_id": "...",
"utterance_index": 0
}
input_audio_buffer.speech_stopped
VAD detected the end of a speech segment.
{
"type": "input_audio_buffer.speech_stopped",
"request_id": "...",
"utterance_index": 0,
"reason": "end_of_speech",
"audio_duration_ms": 3200,
"speech_duration_ms": 2800
}
| Field | Type | Description |
|---|---|---|
| utterance_index | number | Speech segment number |
| reason | string | Stop reason |
| audio_duration_ms | number | Total audio duration |
| speech_duration_ms | number? | Actual speech duration |
| split_offset_ms | number? | Split offset |
| split_rms | number? | Split RMS value |
conversation.item.input_audio_transcription.completed
Primary output event. A speech segment has been transcribed.
{
"type": "conversation.item.input_audio_transcription.completed",
"request_id": "...",
"utterance_index": 0,
"text": "The weather is nice today",
"language": "zh",
"audio_duration_ms": 3200,
"latency_ms": 480,
"segments": [],
"verbose": {}
}
| Field | Type | Description |
|---|---|---|
| utterance_index | number | Speech segment number |
| text | string | Transcribed text |
| language | string | Detected language |
| audio_duration_ms | number | Audio duration |
| latency_ms | number | Processing latency |
| segments | array | Segment details |
| verbose | object | Upstream additional info |
lanson.throttled
Gateway throttle notification, sent at most once per second.
{
"type": "lanson.throttled",
"reason": "concurrent_utterance_limit",
"dropped_audio_frames": 3,
"in_flight_utterances": 2
}
| reason value | Meaning |
|---|---|
| concurrent_utterance_limit | Concurrent utterance limit exceeded |
| upstream_backpressure | Upstream backpressure |
| upstream_connecting | Upstream still connecting |
error
Error event. Can be sent at any time during the WebSocket connection.
{
"type": "error",
"code": "audio_frame_too_large",
"message": "Audio frame exceeds maximum size.",
"request_id": "..."
}
Error codes are listed in [Errors](/docs/api-reference/errors).
Event ordering
session.created
→ [audio frames...]
→ input_audio_buffer.speech_started
→ [more audio...]
→ input_audio_buffer.speech_stopped
→ conversation.item.input_audio_transcription.completed
→ [repeat...]
→ session close