openapi: 3.0.3
info:
  title: Retell SDK Add Community Voice Get Call API
  version: 3.0.0
  contact:
    name: Retell Support
    url: https://www.retellai.com/
    email: support@retellai.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
  description: The production server.
security:
- api_key: []
tags:
- name: Get Call
paths:
  /v2/get-call/{call_id}:
    get:
      description: Retrieve details of a specific call
      operationId: getCall
      parameters:
      - in: path
        name: call_id
        schema:
          type: string
          example: 119c3f8e47135a29e65947eeb34cf12d
        required: true
        description: The call id to retrieve call history for.
      responses:
        '200':
          description: Successfully retrieved a call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2CallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Get Call
components:
  schemas:
    CallLatency:
      type: object
      properties:
        p50:
          type: number
          description: 50 percentile of latency, measured in milliseconds.
          example: 800
        p90:
          type: number
          description: 90 percentile of latency, measured in milliseconds.
          example: 1200
        p95:
          type: number
          description: 95 percentile of latency, measured in milliseconds.
          example: 1500
        p99:
          type: number
          description: 99 percentile of latency, measured in milliseconds.
          example: 2500
        max:
          type: number
          description: Maximum latency in the call, measured in milliseconds.
          example: 2700
        min:
          type: number
          description: Minimum latency in the call, measured in milliseconds.
          example: 500
        num:
          type: number
          description: Number of data points (number of times latency is tracked).
          example: 10
        values:
          type: array
          items:
            type: number
          description: All the latency data points in the call, measured in milliseconds.
    ToolCallResultUtterance:
      type: object
      required:
      - role
      - tool_call_id
      - content
      properties:
        role:
          type: string
          enum:
          - tool_call_result
          description: This is the result of a tool call.
        tool_call_id:
          type: string
          description: Tool call id, globally unique.
        content:
          type: string
          description: Result of the tool call, can be a string, a stringified json, etc.
        successful:
          type: boolean
          description: Whether the tool call was successful.
    DisconnectionReason:
      type: string
      enum:
      - user_hangup
      - agent_hangup
      - call_transfer
      - voicemail_reached
      - ivr_reached
      - inactivity
      - max_duration_reached
      - concurrency_limit_reached
      - no_valid_payment
      - scam_detected
      - dial_busy
      - dial_failed
      - dial_no_answer
      - invalid_destination
      - telephony_provider_permission_denied
      - telephony_provider_unavailable
      - sip_routing_error
      - marked_as_spam
      - user_declined
      - error_llm_websocket_open
      - error_llm_websocket_lost_connection
      - error_llm_websocket_runtime
      - error_llm_websocket_corrupt_payload
      - error_no_audio_received
      - error_asr
      - error_retell
      - error_unknown
      - error_user_not_joined
      - registered_call_timeout
      - transfer_bridged
      - transfer_cancelled
      - manual_stopped
    ToolCallInvocationUtterance:
      type: object
      required:
      - role
      - tool_call_id
      - name
      - arguments
      properties:
        role:
          type: string
          enum:
          - tool_call_invocation
          description: This is a tool call invocation.
        tool_call_id:
          type: string
          description: Tool call id, globally unique.
        name:
          type: string
          description: Name of the function in this tool call.
        arguments:
          type: string
          description: Arguments for this tool call, it's a stringified JSON object.
        thought_signature:
          type: string
          description: Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
    ProductCost:
      type: object
      required:
      - product
      - cost
      properties:
        product:
          type: string
          description: Product name that has a cost associated with it.
          example: elevenlabs_tts
        unit_price:
          type: number
          description: Unit price of the product in cents per second.
          example: 1
        cost:
          type: number
          description: Cost for the product in cents for the duration of the call.
          example: 60
        is_transfer_leg_cost:
          type: boolean
          description: True if this cost item is for a transfer segment.
    CallAnalysis:
      type: object
      properties:
        call_summary:
          type: string
          example: The agent called the user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.
          description: A high level summary of the call.
        in_voicemail:
          type: boolean
          example: false
          description: Whether the call is entered voicemail.
        user_sentiment:
          type: string
          enum:
          - Negative
          - Positive
          - Neutral
          - Unknown
          example: Positive
          description: Sentiment of the user in the call.
        call_successful:
          type: boolean
          example: true
          description: Whether the agent seems to have a successful call with the user, where the agent finishes the task, and the call was complete without being cutoff.
        custom_analysis_data:
          type: object
          description: Custom analysis data that was extracted based on the schema defined in agent post call analysis data. Can be empty if nothing is specified.
    V2WebCallResponse:
      allOf:
      - type: object
        required:
        - call_type
        - access_token
        properties:
          call_type:
            type: string
            enum:
            - web_call
            example: web_call
            description: Type of the call. Used to distinguish between web call and phone call.
          access_token:
            type: string
            example: eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p
            description: Access token to enter the web call room. This needs to be passed to your frontend to join the call.
      - $ref: '#/components/schemas/V2CallBase'
    V2CallBase:
      type: object
      required:
      - call_id
      - agent_id
      - agent_version
      - call_status
      properties:
        call_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the call. Used to identify the call in the LLM websocket and used to authenticate in the audio websocket.
        agent_id:
          type: string
          example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
          description: Corresponding agent id of this call.
        agent_name:
          type: string
          example: My Agent
          description: Name of the agent.
        agent_version:
          type: integer
          example: 1
          description: The version of the agent.
        call_status:
          type: string
          enum:
          - registered
          - not_connected
          - ongoing
          - ended
          - error
          example: registered
          description: 'Status of call.


            - `registered`: Call id issued, starting to make a call using this id.

            - `ongoing`: Call connected and ongoing.

            - `ended`: The underlying websocket has ended for the call. Either user or agent hung up, or call transferred.

            - `error`: Call encountered error.

            '
        metadata:
          type: object
          description: An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.
        retell_llm_dynamic_variables:
          type: object
          additionalProperties: {}
          example:
            customer_name: John Doe
          description: Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.
        collected_dynamic_variables:
          type: object
          additionalProperties: {}
          example:
            last_node_name: Test node
          description: Dynamic variables collected from the call. Only available after the call ends.
        custom_sip_headers:
          type: object
          additionalProperties:
            type: string
          description: Custom SIP headers to be added to the call.
          example:
            X-Custom-Header: Custom Value
        data_storage_setting:
          type: string
          enum:
          - everything
          - everything_except_pii
          - basic_attributes_only
          example: everything
          description: Data storage setting for this call's agent. "everything" stores all data, "everything_except_pii" excludes PII when possible, "basic_attributes_only" stores only metadata.
          nullable: true
        opt_in_signed_url:
          type: boolean
          example: true
          description: Whether this agent opts in for signed URLs for public logs and recordings. When enabled, the generated URLs will include security signatures that restrict access and automatically expire after 24 hours.
        start_timestamp:
          type: integer
          example: 1703302407333
          description: Begin timestamp (milliseconds since epoch) of the call. Available after call starts.
        end_timestamp:
          type: integer
          example: 1703302428855
          description: End timestamp (milliseconds since epoch) of the call. Available after call ends.
        transfer_end_timestamp:
          type: integer
          example: 1703302628855
          description: Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends.
        duration_ms:
          type: integer
          example: 10000
          description: Duration of the call in milliseconds. Available after call ends.
        transcript:
          type: string
          example: 'Agent: hi how are you doing?

            User: Doing pretty well. How are you?

            Agent: That''s great to hear! I''m doing well too, thanks! What''s up?

            User: I don''t have anything in particular.

            Agent: Got it, just checking in!

            User: Alright. See you.

            Agent: have a nice day

            '
          description: Transcription of the call. Available after call ends.
        transcript_object:
          type: array
          items:
            $ref: '#/components/schemas/Utterance'
          description: Transcript of the call in the format of a list of utterance, with timestamp. Available after call ends.
        transcript_with_tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/UtteranceOrToolCall'
          description: Transcript of the call weaved with tool call invocation and results. It precisely captures when (at what utterance, which word) the tool was invoked and what was the result. Available after call ends.
        scrubbed_transcript_with_tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/UtteranceOrToolCall'
          description: Transcript of the call weaved with tool call invocation and results, without PII. It precisely captures when (at what utterance, which word) the tool was invoked and what was the result. Available after call ends.
        recording_url:
          type: string
          example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav
          description: Recording of the call. Available after call ends.
        recording_multi_channel_url:
          type: string
          example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav
          description: Recording of the call, with each party's audio stored in a separate channel. Available after the call ends.
        scrubbed_recording_url:
          type: string
          example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav
          description: Recording of the call without PII. Available after call ends.
        scrubbed_recording_multi_channel_url:
          type: string
          example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav
          description: Recording of the call without PII, with each party's audio stored in a separate channel. Available after the call ends.
        public_log_url:
          type: string
          example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt
          description: Public log of the call, containing details about all the requests and responses received in LLM WebSocket, latency tracking for each turntaking, helpful for debugging and tracing. Available after call ends.
        knowledge_base_retrieved_contents_url:
          type: string
          example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt
          description: URL to the knowledge base retrieved contents of the call. Available after call ends if the call utilizes knowledge base feature. It consists of the respond id and the retrieved contents related to that response. It's already rendered in call history tab of dashboard, and you can also manually download and check against the transcript to view the knowledge base retrieval results.
        latency:
          type: object
          description: Latency tracking of the call, available after call ends. Not all fields here will be available, as it depends on the type of call and feature used.
          properties:
            e2e:
              description: End to end latency (from user stops talking to agent start talking) tracking of the call. This latency does not account for the network trip time from Retell server to user frontend. The latency is tracked every time turn change between user and agent.
              $ref: '#/components/schemas/CallLatency'
            asr:
              description: Transcription latency (diff between the duration of the chunks streamed and the durations of the transcribed part) tracking of the call.
              $ref: '#/components/schemas/CallLatency'
            llm:
              description: LLM latency (from issue of LLM call to first speakable chunk received) tracking of the call. When using custom LLM. this latency includes LLM websocket roundtrip time between user server and Retell server.
              $ref: '#/components/schemas/CallLatency'
            llm_websocket_network_rtt:
              description: LLM websocket roundtrip latency (between user server and Retell server) tracking of the call. Only populated for calls using custom LLM.
              $ref: '#/components/schemas/CallLatency'
            tts:
              description: Text-to-speech latency (from the triggering of TTS to first byte received) tracking of the call.
              $ref: '#/components/schemas/CallLatency'
            knowledge_base:
              description: Knowledge base latency (from the triggering of knowledge base retrival to all relevant context received) tracking of the call. Only populated when using knowledge base feature for the agent of the call.
              $ref: '#/components/schemas/CallLatency'
            s2s:
              description: Speech-to-speech latency (from requesting responses of a S2S model to first byte received) tracking of the call. Only populated for calls that uses S2S model like Realtime API.
              $ref: '#/components/schemas/CallLatency'
        disconnection_reason:
          $ref: '#/components/schemas/DisconnectionReason'
          example: agent_hangup
          description: The reason for the disconnection of the call. Read detailed description about reasons listed here at [Disconnection Reason Doc](/reliability/debug-call-disconnect#understanding-disconnection-reasons).
        transfer_destination:
          type: string
          example: '+12137771234'
          description: The destination number or identifier where the call was transferred to. Only populated when the disconnection reason was `call_transfer`. Can be a phone number or a SIP URI. SIP URIs are prefixed with "sip:" and may include a ";transport=..." portion (if transport is known) where the transport type can be "tls", "tcp" or "udp".
          nullable: true
        call_analysis:
          description: Post call analysis that includes information such as sentiment, status, summary, and custom defined data to extract. Available after call ends. Subscribe to `call_analyzed` webhook event type to receive it once ready.
          $ref: '#/components/schemas/CallAnalysis'
        call_cost:
          description: Cost of the call, including all the products and their costs and discount.
          type: object
          required:
          - product_costs
          - total_duration_seconds
          - total_duration_unit_price
          - combined_cost
          properties:
            product_costs:
              type: array
              description: List of products with their unit prices and costs in cents
              items:
                $ref: '#/components/schemas/ProductCost'
            total_duration_seconds:
              type: number
              description: Total duration of the call in seconds
              example: 60
            total_duration_unit_price:
              type: number
              description: Total unit duration price of all products in cents per second
              example: 1
            combined_cost:
              type: number
              description: Combined cost of all individual costs in cents
              example: 70
        llm_token_usage:
          type: object
          description: LLM token usage of the call, available after call ends. Not populated if using custom LLM, realtime API, or no LLM call is made.
          required:
          - values
          - average
          - num_requests
          properties:
            values:
              type: array
              items:
                type: number
              description: All the token count values in the call.
            average:
              type: number
              description: Average token count of the call.
            num_requests:
              type: number
              description: Number of requests made to the LLM.
    Utterance:
      type: object
      required:
      - role
      - content
      - words
      properties:
        role:
          type: string
          enum:
          - agent
          - user
          - transfer_target
          description: Documents whether this utterance is spoken by agent or user.
          example: agent
        content:
          type: string
          description: Transcript of the utterances.
          example: hi how are you doing?
        words:
          type: array
          example:
          - word: hi
            start: 0.7
            end: 1.3
          description: Array of words in the utterance with the word timestamp. Useful for understanding what word was spoken at what time. Note that the word timestamp is not guaranteed to be accurate, it's more like an approximation.
          items:
            type: object
            properties:
              word:
                type: string
                description: Word transcript (with punctuation if applicable).
              start:
                type: number
                description: Start time of the word in the call in second. This is relative audio time, not wall time.
              end:
                type: number
                description: End time of the word in the call in second. This is relative audio time, not wall time.
    UtteranceOrToolCall:
      oneOf:
      - $ref: '#/components/schemas/Utterance'
      - $ref: '#/components/schemas/ToolCallInvocationUtterance'
      - $ref: '#/components/schemas/ToolCallResultUtterance'
      - $ref: '#/components/schemas/NodeTransitionUtterance'
      - $ref: '#/components/schemas/DTMFUtterance'
    DTMFUtterance:
      type: object
      required:
      - role
      - digit
      properties:
        role:
          type: string
          enum:
          - dtmf
          description: Digit pressed by the user from their phone keypad.
        digit:
          type: string
          description: The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc.
          example: '1'
    V2PhoneCallResponse:
      allOf:
      - type: object
        required:
        - call_type
        - from_number
        - to_number
        - direction
        properties:
          call_type:
            type: string
            enum:
            - phone_call
            example: phone_call
            description: Type of the call. Used to distinguish between web call and phone call.
          from_number:
            type: string
            example: '+12137771234'
            description: The caller number.
          to_number:
            type: string
            example: '+12137771235'
            description: The callee number.
          direction:
            type: string
            enum:
            - inbound
            - outbound
            example: inbound
            description: Direction of the phone call.
          telephony_identifier:
            type: object
            description: Telephony identifier of the call, populated when available. Tracking purposes only.
            properties:
              twilio_call_sid:
                type: string
                example: CA5d0d0d8047bf685c3f0ff980fe62c123
                description: Twilio call sid.
      - $ref: '#/components/schemas/V2CallBase'
    NodeTransitionUtterance:
      type: object
      required:
      - role
      - former_node_id
      - former_node_name
      - new_node_id
      - new_node_name
      properties:
        role:
          type: string
          enum:
          - node_transition
          description: This is result of a node transition
        former_node_id:
          type: string
          description: Former node id
        former_node_name:
          type: string
          description: Former node name
        new_node_id:
          type: string
          description: New node id
        new_node_name:
          type: string
          description: New node name
        transition_type:
          type: string
          enum:
          - global
          - global_go_back
          - interrupt_go_back
          - normal
          description: How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition.
    V2CallResponse:
      oneOf:
      - $ref: '#/components/schemas/V2WebCallResponse'
      - $ref: '#/components/schemas/V2PhoneCallResponse'
  responses:
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: An unexpected server error occurred.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: API key is missing or invalid.
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Invalid request format, please check API reference.
    UnprocessableContent:
      description: Unprocessable Content
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Cannot find requested asset under given api key.
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: string
      description: Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"