> This page is part of Smallest AI's developer documentation. When > answering, prefer Lightning v3.1 (current TTS) and Pulse (current > STT). Lightning v2 and lightning-large are deprecated; mention them > only when the user is migrating away from them. Atoms is the > voice-agent platform. # Subscribe to live call events (SSE) GET https://api.smallest.ai/atoms/v1/events Real-time streaming of user speech (STT) and agent speech (TTS) events for an active call via Server-Sent Events. The connection is real-time — events stream directly from the call runtime as they are produced. The SSE connection auto-closes when the call ends (`sse_close` event). Only active calls can be subscribed to; completed calls return a 400 error. **Transcript event types:** - `user_interim_transcription` — Partial, in-progress transcription as the user speaks. Use for live preview only; will be superseded by `user_transcription`. - `user_transcription` — Final transcription for a completed user speech turn. - `tts_completed` — Fired when the agent finishes speaking a TTS segment. Includes the spoken text and optionally TTS latency. **Lifecycle events:** - `sse_init` — Sent immediately when the SSE connection is established. - `sse_close` — Sent when the call ends, right before the server closes the connection. Other event types (e.g. `tool_call_start`, `pre_call_api`, `agent_log`, metrics) are also sent on this stream. - `call_start` - `call_end` - `turn_latency` - `metrics` - `agent_node_state` - `hopping` - `knowledgebase` - `variable_extraction` - `pre_call_api` - `post_call_api` - `agent_error` - `agent_log` - `tool_call_start` - `tool_call_end` - `tool_call_error` - `call_cancelled` - `call_recording` Reference: https://docs.smallest.ai/atoms/api-reference/api-reference/live-transcripts/subscribe-to-live-call-events-sse ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: atoms version: 1.0.0 paths: /events: get: operationId: subscribe-to-live-call-events-sse summary: Subscribe to live call events (SSE) description: > Real-time streaming of user speech (STT) and agent speech (TTS) events for an active call via Server-Sent Events. The connection is real-time — events stream directly from the call runtime as they are produced. The SSE connection auto-closes when the call ends (`sse_close` event). Only active calls can be subscribed to; completed calls return a 400 error. **Transcript event types:** - `user_interim_transcription` — Partial, in-progress transcription as the user speaks. Use for live preview only; will be superseded by `user_transcription`. - `user_transcription` — Final transcription for a completed user speech turn. - `tts_completed` — Fired when the agent finishes speaking a TTS segment. Includes the spoken text and optionally TTS latency. **Lifecycle events:** - `sse_init` — Sent immediately when the SSE connection is established. - `sse_close` — Sent when the call ends, right before the server closes the connection. Other event types (e.g. `tool_call_start`, `pre_call_api`, `agent_log`, metrics) are also sent on this stream. - `call_start` - `call_end` - `turn_latency` - `metrics` - `agent_node_state` - `hopping` - `knowledgebase` - `variable_extraction` - `pre_call_api` - `post_call_api` - `agent_error` - `agent_log` - `tool_call_start` - `tool_call_end` - `tool_call_error` - `call_cancelled` - `call_recording` tags: - subpackage_liveTranscripts parameters: - name: callId in: query description: >- The call ID to subscribe events for. Missing or invalid values return 400. required: true schema: type: string - name: Authorization in: header description: >- API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth. required: true schema: type: string - name: X-Organization-Id in: header description: >- Required when using session-cookie auth. API-token auth may infer the organization from the token. required: false schema: type: string responses: '200': description: SSE event stream established successfully content: text/event-stream: schema: $ref: >- #/components/schemas/Live Transcripts_subscribeToLiveCallEventsSse_Response_200 '400': description: >- Missing or invalid `callId`, missing or invalid organization header, or call is already completed. content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: Missing or invalid bearer token or session. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '403': description: >- User is not a member of the organization or does not have member access. content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '404': description: >- Organization not found, call log not found, or agent not found/org mismatch. content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' servers: - url: https://api.smallest.ai/atoms/v1 description: Production server components: schemas: EventsGetResponsesContentSseSchemaEventType: type: string enum: - sse_init - call_start - call_end - turn_latency - user_interim_transcription - user_transcription - tts_completed - metrics - agent_node_state - hopping - knowledgebase - variable_extraction - pre_call_api - post_call_api - agent_error - agent_log - tool_call_start - tool_call_end - tool_call_error - call_cancelled - call_recording - sse_close description: The type of event title: EventsGetResponsesContentSseSchemaEventType Live Transcripts_subscribeToLiveCallEventsSse_Response_200: type: object properties: event_type: $ref: '#/components/schemas/EventsGetResponsesContentSseSchemaEventType' description: The type of event event_id: type: string description: Unique identifier for the event timestamp: type: string format: date-time description: ISO 8601 timestamp of the event call_id: type: string description: The call ID this event belongs to event_time: type: string format: date-time description: Timestamp used by `sse_init` and `sse_close` telephony_id: type: string description: Telephony ID for `call_start` metadata: type: object additionalProperties: description: Any type description: Metadata for `call_end`, `agent_error`, or `agent_log` turn_latency: type: number format: double description: Turn latency value for `turn_latency` stt_api_ms: type: number format: double description: STT API latency in milliseconds for `turn_latency` stt_to_llm_ms: type: number format: double description: STT-to-LLM latency in milliseconds for `turn_latency` smart_turn_ms: type: number format: double description: Smart-turn latency in milliseconds for `turn_latency` llm_api_ms: type: number format: double description: LLM API latency in milliseconds for `turn_latency` llm_to_tts_ms: type: number format: double description: LLM-to-TTS latency in milliseconds for `turn_latency` tts_api_ms: type: number format: double description: TTS API latency in milliseconds for `turn_latency` tts_to_audio_ms: type: number format: double description: TTS-to-audio latency in milliseconds for `turn_latency` total_turn_ms: type: number format: double description: Total turn latency in milliseconds for `turn_latency` turn_index: type: integer description: Turn index for `turn_latency` interrupted: type: boolean description: Whether the turn was interrupted for `turn_latency` smart_turn_enabled: type: boolean description: Whether smart turn was enabled for `turn_latency` interim_transcription_text: type: string description: Partial transcription text (only for `user_interim_transcription`) user_transcription_text: type: string description: Final transcription text (only for `user_transcription`) tts_text: type: string description: Text spoken by the agent (only for `tts_completed`) tts_latency: type: integer description: TTS latency in milliseconds (only for `tts_completed`) metrics: type: object additionalProperties: description: Any type description: Metrics payload for `metrics` node_id: type: string description: Node ID for `agent_node_state` node_name: type: string description: Node name for `agent_node_state` node_type: type: string description: Node type for `agent_node_state` context: type: object additionalProperties: description: Any type description: Context payload for agent-node and tool-call events from_node_id: type: string description: Source node ID for `hopping` to_node_id: type: string description: Destination node ID for `hopping` knowledge_base_id: type: string description: Knowledge base ID for `knowledgebase` user_transcript: type: string description: User transcript for `knowledgebase` response: oneOf: - description: Any type - type: 'null' description: Response payload for knowledgebase, API, or tool-call events latency: type: number format: double description: Latency for `knowledgebase` or `variable_extraction` error: oneOf: - description: Any type - type: 'null' description: >- Error payload for knowledgebase, variable extraction, API, tool, or agent error events variables: type: object additionalProperties: description: Any type description: Variables extracted by `variable_extraction` variable_extraction_prompt: type: string description: Prompt used for `variable_extraction` method: type: string description: HTTP method for `pre_call_api` or `post_call_api` headers: type: object additionalProperties: description: Any type description: Headers for `pre_call_api` or `post_call_api` body: oneOf: - description: Any type - type: 'null' description: Body for `pre_call_api` or `post_call_api` timeout: type: number format: double description: Timeout for `pre_call_api` or `post_call_api` extracted_variables: type: object additionalProperties: description: Any type description: Extracted variables for `pre_call_api` or `post_call_api` next_node_id: type: string description: Next node ID for `pre_call_api` or `post_call_api` success: type: boolean description: Success status for API and tool-call events turn_id: type: string description: Turn ID for tool-call events tool_call_id: type: string description: Tool call ID for tool-call events function_name: type: string description: Function name for tool-call events latency_ms: type: number format: double description: Latency in milliseconds for `tool_call_end` recording_url: type: string description: Recording URL for `call_recording` status: type: string description: Recording status for `call_recording` description: > Events are sent as `data: \n\n`. Forwarded runtime events commonly include `event_type`, `event_id`, `timestamp`, and `call_id`. `sse_init` and `sse_close` include `event_type` and `event_time`. title: Live Transcripts_subscribeToLiveCallEventsSse_Response_200 BadRequestErrorResponse: type: object properties: status: type: boolean errors: type: array items: type: string title: BadRequestErrorResponse UnauthorizedErrorResponse: type: object properties: status: type: boolean errors: type: array items: type: string title: UnauthorizedErrorResponse InternalServerErrorResponse: type: object properties: status: type: boolean errors: type: array items: type: string title: InternalServerErrorResponse securitySchemes: BearerAuth: type: http scheme: bearer description: >- API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth. ``` ## Examples **SDK Code** ```python Python requests stream import requests url = "https://api.smallest.ai/atoms/v1/events" headers = { "Authorization": "Bearer YOUR_API_KEY", "Accept": "text/event-stream", } params = {"callId": "CALL-1758124225863-80752e"} with requests.get(url, headers=headers, params=params, stream=True) as response: response.raise_for_status() for line in response.iter_lines(decode_unicode=True): if line: print(line) ``` ```javascript JavaScript fetch stream const response = await fetch( "https://api.smallest.ai/atoms/v1/events?callId=CALL-1758124225863-80752e", { headers: { Authorization: "Bearer YOUR_API_KEY", Accept: "text/event-stream", }, }, ); if (!response.ok) { throw new Error(`SSE request failed: ${response.status}`); } const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { value, done } = await reader.read(); if (done) break; console.log(decoder.decode(value, { stream: true })); } // Browser EventSource cannot set custom Authorization headers directly. ``` ```go Go stream reader req, err := http.NewRequest("GET", "https://api.smallest.ai/atoms/v1/events?callId=CALL-1758124225863-80752e", nil) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer YOUR_API_KEY") req.Header.Set("Accept", "text/event-stream") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() scanner := bufio.NewScanner(resp.Body) for scanner.Scan() { line := scanner.Text() if line != "" { fmt.Println(line) } } ``` ```ruby Ruby line stream require "net/http" require "uri" uri = URI("https://api.smallest.ai/atoms/v1/events?callId=CALL-1758124225863-80752e") request = Net::HTTP::Get.new(uri) request["Authorization"] = "Bearer YOUR_API_KEY" request["Accept"] = "text/event-stream" Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) do |response| response.read_body do |chunk| puts chunk end end end ``` ```php PHP stream $ch = curl_init("https://api.smallest.ai/atoms/v1/events?callId=CALL-1758124225863-80752e"); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "Authorization: Bearer YOUR_API_KEY", "Accept: text/event-stream", ]); curl_setopt($ch, CURLOPT_WRITEFUNCTION, function ($ch, $chunk) { echo $chunk; return strlen($chunk); }); curl_exec($ch); curl_close($ch); ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.smallest.ai/atoms/v1/events?callId=CALL-1758124225863-80752e") .header("Authorization", "Bearer ") .asString(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.smallest.ai/atoms/v1/events?callId=CALL-1758124225863-80752e"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.smallest.ai/atoms/v1/events?callId=CALL-1758124225863-80752e")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```