Retell AI List Calls API

openapi: 3.2.0
info:
  title: Retell SDK Add Community Voice List Calls 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: List Calls
paths:
  /v2/list-calls:
    post:
      description: Retrieve call details
      operationId: listCalls
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_criteria:
                  type: object
                  description: Filter criteria for the calls to retrieve.
                  example:
                    call_id:
                    - call_5a82f0a43ea0977566b1104fcfc
                    agent_id:
                    - agent_oBeDLoLOeuAbiuaMFXRtDOLriT12345
                    call_status:
                    - ended
                    call_type:
                    - phone_call
                    direction:
                    - inbound
                    user_sentiment:
                    - Positive
                    call_successful:
                    - true
                    start_timestamp:
                      upper_threshold: 1738475421000
                      lower_threshold: 1738475411000
                    metadata.customer_id:
                    - cust_123
                    dynamic_variables.user_name:
                    - John
                  properties:
                    call_id:
                      type: array
                      items:
                        type: string
                        minLength: 1
                      description: Only retrieve calls with specific call id(s).
                    agent_id:
                      type: array
                      items:
                        type: string
                        minLength: 1
                      description: Only retrieve calls that are made with specific agent(s).
                    version:
                      type: array
                      items:
                        type: integer
                      description: The version of the agent to use for the call.
                    call_status:
                      type: array
                      items:
                        type: string
                        enum:
                        - not_connected
                        - ongoing
                        - ended
                        - error
                      description: Only retrieve calls with specific call status(es).
                    in_voicemail:
                      type: array
                      items:
                        type: boolean
                      description: Only retrieve calls that are in voicemail or not in voicemail.
                    disconnection_reason:
                      type: array
                      items:
                        $ref: '#/components/schemas/DisconnectionReason'
                      description: Only retrieve calls with specific disconnection reason(s).
                    from_number:
                      type: array
                      items:
                        type: string
                        minLength: 1
                      description: Only retrieve calls with specific from number(s).
                    to_number:
                      type: array
                      items:
                        type: string
                        minLength: 1
                      description: Only retrieve calls with specific to number(s).
                    batch_call_id:
                      type: array
                      items:
                        type: string
                      description: Only retrieve calls with specific batch call id(s).
                    call_type:
                      type: array
                      items:
                        type: string
                        enum:
                        - web_call
                        - phone_call
                      description: Only retrieve calls with specific call type(s).
                    direction:
                      type: array
                      items:
                        type: string
                        enum:
                        - inbound
                        - outbound
                      description: Only retrieve calls with specific direction(s).
                    user_sentiment:
                      type: array
                      items:
                        type: string
                        enum:
                        - Negative
                        - Positive
                        - Neutral
                        - Unknown
                      description: Only retrieve calls with specific user sentiment(s).
                    call_successful:
                      type: array
                      items:
                        type: boolean
                      description: Only retrieve calls with specific call successful(s).
                    start_timestamp:
                      type: object
                      properties:
                        upper_threshold:
                          type: integer
                        lower_threshold:
                          type: integer
                      description: Only retrieve calls with specific range of start timestamp(s).
                    end_timestamp:
                      type: object
                      properties:
                        upper_threshold:
                          type: integer
                        lower_threshold:
                          type: integer
                      description: Only retrieve calls with specific range of end timestamp(s).
                    duration_ms:
                      type: object
                      properties:
                        upper_threshold:
                          type: integer
                        lower_threshold:
                          type: integer
                      description: Only retrieve calls with specific range of duration(s).
                    e2e_latency_p50:
                      type: object
                      properties:
                        upper_threshold:
                          type: integer
                        lower_threshold:
                          type: integer
                    metadata:
                      type: object
                      description: 'Filter by metadata fields using dot notation (e.g., `metadata.customer_id`).

                        Values are matched exactly as strings.

                        '
                      additionalProperties:
                        type: array
                        items:
                          type: string
                      example:
                        metadata.customer_id:
                        - cust_123
                    dynamic_variables:
                      type: object
                      description: 'Filter by dynamic variables using dot notation (e.g., `dynamic_variables.name`).

                        Values are matched exactly as strings.

                        '
                      additionalProperties:
                        type: array
                        items:
                          type: string
                      example:
                        dynamic_variables.user_name:
                        - John
                sort_order:
                  type: string
                  enum:
                  - ascending
                  - descending
                  default: descending
                  description: The calls will be sorted by `start_timestamp`, whether to return the calls in ascending or descending order.
                limit:
                  type: integer
                  default: 50
                  description: Limit the number of calls returned. Default 50, Max 1000. To retrieve more than 1000, use pagination_key to continue fetching the next page.
                pagination_key:
                  type: string
                  description: The pagination key to continue fetching the next page of calls. Pagination key is represented by a call id here, and it's exclusive (not included in the fetched calls). The last call id from the list calls is usually used as pagination key here. If not set, will start from the beginning.
      responses:
        '200':
          description: Successfully retrieved calls.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/V2CallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - List Calls
  /v3/list-calls:
    post:
      description: List calls with unified cursor pagination response.
      operationId: listCallsV3
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_criteria:
                  $ref: '#/components/schemas/CallFilter'
                sort_order:
                  type: string
                  enum:
                  - ascending
                  - descending
                  default: descending
                  description: Sort calls by `start_timestamp` in ascending or descending order.
                limit:
                  type: integer
                  default: 50
                  maximum: 1000
                  description: Maximum number of calls to return.
                skip:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Number of records to skip for pagination.
                pagination_key:
                  type: string
                  description: Opaque pagination cursor from a previous response.
              not:
                required:
                - skip
                - pagination_key
      responses:
        '200':
          description: Successfully retrieved calls.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponseBase'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/V3CallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - List Calls
components:
  responses:
    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.
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              message:
                type: string
                example: Account rate limited, please throttle your requests.
    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.
    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.
  schemas:
    NumberFilter:
      type: object
      required:
      - type
      - op
      - value
      properties:
        type:
          type: string
          enum:
          - number
        op:
          type: string
          enum:
          - eq
          - ne
          - gt
          - ge
          - lt
          - le
          description: 'eq: equal, ne: not equal, gt: greater than, ge: greater than or equal, lt: less than, le: less than or equal'
        value:
          type: number
    ToolCallFilter:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The tool call name to filter on.
        latency_ms:
          oneOf:
          - $ref: '#/components/schemas/NumberFilter'
          - $ref: '#/components/schemas/RangeFilter'
          description: Filter by tool call latency in milliseconds.
        success:
          $ref: '#/components/schemas/BooleanFilter'
          description: Filter by tool call success status.
    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.
    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.
    PaginatedResponseBase:
      type: object
      properties:
        pagination_key:
          type: string
          description: Pagination key for the next page.
        has_more:
          type: boolean
          description: Whether more results are available.
    AgentFilter:
      type: object
      required:
      - agent_id
      properties:
        agent_id:
          type: string
          minLength: 1
          description: The agent ID to filter on.
        version:
          type: array
          items:
            type: number
          description: Specific versions to filter on. If not provided, all versions are included.
    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'
    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'
    EnumFilter:
      type: object
      required:
      - type
      - op
      - value
      properties:
        type:
          type: string
          enum:
          - enum
        op:
          type: string
          enum:
          - in
          description: 'in: value is one of the listed values'
        value:
          type: array
          items:
            type: string
    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
    RangeFilter:
      type: object
      required:
      - type
      - op
      - value
      properties:
        type:
          type: string
          enum:
          - range
        op:
          type: string
          enum:
          - bt
          description: 'bt: between'
        value:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: number
          description: '[lower_bound, upper_bound]'
    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.
    BooleanFilter:
      type: object
      required:
      - type
      - op
      - value
      properties:
        type:
          type: string
          enum:
          - boolean
        op:
          type: string
          enum:
          - eq
        value:
          type: boolean
    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'
    V3CallResponse:
      allOf:
      - $ref: '#/components/schemas/V2CallResponse'
      - type: object
        description: V3 list calls response. Transcript fields are intentionally omitted.
        not:
          anyOf:
          - required:
            - transcript
          - required:
            - transcript_object
          - required:
            - transcript_with_tool_calls
          - required:
            - scrubbed_transcript_with_tool_calls
    CallFilter:
      type: object
      description: Filter criteria for calls. All conditions are implicitly connected with AND.
      properties:
        agent:
          type: array
          items:
            $ref: '#/components/schemas/AgentFilter'
          description: Filter by agent(s). Agent filters are connected by OR.
        call_id:
          $ref: '#/components/schemas/StringFilter'
          description: Filter by call ID.
        batch_call_id:
          $ref: '#/components/schemas/StringFilter'
          description: Filter by batch call ID.
        call_status:
          allOf:
          - $ref: '#/components/schemas/EnumFilter'
          - description: Filter by call status.
            properties:
              value:
                items:
                  enum:
                  - not_connected
                  - ongoing
                  - ended
                  - error
        in_voicemail:
          $ref: '#/components/schemas/BooleanFilter'
          description: Filter by whether the call is in voicemail.
        disconnection_reason:
          allOf:
          - $ref: '#/components/schemas/EnumFilter'
          - description: Filter by disconnection reason.
            properties:
              value:
                items:
                  $ref: '#/components/schemas/DisconnectionReason'
        from_number:
          $ref: '#/components/schemas/StringFilter'
          description: Filter by from number.
        to_number:
          $ref: '#/components/schemas/StringFilter'
          description: Filter by to number.
        call_type:
          allOf:
          - $ref: '#/components/schemas/EnumFilter'
          - description: Filter by call type.
            properties:
              value:
                items:
                  enum:
                  - web_call
                  - phone_call
        direction:
          allOf:
          - $ref: '#/components/schemas/EnumFilter'
          - description: Filter by call direction.
            properties:
              value:
                items:
                  enum:
                  - inbound
                  - outbound
        user_sentiment:
          allOf:
          - $ref: '#/components/schemas/EnumFilter'
          - description: Filter by user sentiment.
            properties:
              value:
                items:
                  enum:
                  - Negative
                  - Positive
                  - Neutral
                  - Unknown
        data_storage_setting:
          allOf:
          - $ref: '#/components/schemas/EnumFilter'
          - description: Filter by data storage setting.
            properties:
              value:
                items:
                  enum:
                  - everything
                  - everything_except_pii
                  - basic_attributes_only
        call_successful:
          $ref: '#/components/schemas/BooleanFilter'
          description: Filter by whether the call was successful.
        start_timestamp:
          oneOf:
          - $ref: '#/components/schemas/NumberFilter'
          - $ref: '#/components/schemas/RangeFilter'
          description: Filter by call start timestamp (epoch ms).
        end_timestamp:
          oneOf:
          - $ref: '#/components/schemas/NumberFilter'
          - $ref: '#/components/schemas/RangeFilter'
          description: Filter by call end timestamp (epoch ms).
        duration_ms:
          oneOf:
          - $ref: '#/components/schemas/NumberFilter'
          - $ref: '#/components/schemas/RangeFilter'
          description: Filter by call duration in milliseconds.
        combined_cost:
          oneOf:
          - $ref: '#/components/schemas/NumberFilter'
          - $ref: '#/components/schemas/RangeFilter'
          description: Filter by combined cost of the call.
        e2e_latency_p50:
          oneOf:
          - $ref: '#/components/schemas/NumberFilter'
          - $ref: '#/components/schemas/RangeFilter'
          description: Filter by end-to-end latency p50.
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCallFilter'
          description: Filter by tool call criteria. Tool call filters are connected by AND.
        custom_analysis_data:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldFilter'
          description: Filter by custom analysis data fields.
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldFilter'
          description: Filter by custom attributes fields.
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldFilter'
          description: Filter by metadata fields.
        dynamic_variables:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/StringFilter'
            - type: object
              required:
              - key
              properties:
                key:
                  type: string
                  description: The dynamic variable name to filter on.
          description: Filter by dynamic variables.
    ValueFilter:
      oneOf:
      - $ref: '#/components/schemas/StringFilter'
      - $ref: '#/components/schemas/NumberFilter'
      - $ref: '#/components/schemas/BooleanFilter'
      - $ref: '#/components/schemas/RangeFilter'
      - $ref: '#/components/schemas/EnumFilter'
      - $ref: '#/components/schemas/PresentFilter'
    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.
    CustomFieldFilter:
      description: A filter on a custom field, identified by key.
      allOf:
      - $ref: '#/components/schemas/ValueFilter'
      - type: object
        required:
        - key
        properties:
          key:
            type: string
            description: The field name to filter on.
    PresentFilter:
      type: object
      required:
      - type
      - op
      properties:
        type:
          type: string
          enum:
          - present
        op:
          type: string
          enum:
          - pr
          - np
          description: 'pr: present (has value), np: not present'
    StringFilter:
      type: object
      required:
      - type
      - op
      - value
      properties:
        type:
          type: string
          enum:
          - string
        op:
          type: string
          enum:
          - eq
          - ne
          - sw
          - ew
          - co
          description: 'eq: equal, ne: not equal, sw: starts with, ew: ends with, co: contains'
        value:
          type: string
    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.
    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.
    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 cal

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-list-calls-api-openapi.yml