Retell AI List Chats API

openapi: 3.2.0
info:
  title: Retell SDK List Chats 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 Chats
paths:
  /v3/list-chats:
    post:
      description: List chats with unified cursor pagination response.
      operationId: listChatsV3
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                filter_criteria:
                  type: object
                  description: Filter criteria for chats to retrieve.
                  additionalProperties: true
                sort_order:
                  type: string
                  enum:
                  - ascending
                  - descending
                  default: descending
                  description: Sort chats by `start_timestamp` in ascending or descending order.
                limit:
                  type: integer
                  default: 50
                  maximum: 1000
                  description: Maximum number of chats 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 chats.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponseBase'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/V3ChatResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - List Chats
      summary: List chats V3
      x-summary-source: derived
components:
  schemas:
    StateTransitionMessageBase:
      type: object
      required:
      - role
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        role:
          type: string
          enum:
          - state_transition
          description: This is a state transition.
        former_state_name:
          type: string
          description: Former state name
        new_state_name:
          type: string
          description: New state name
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
    ChatResponse:
      type: object
      required:
      - chat_id
      - agent_id
      - chat_status
      properties:
        chat_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the chat.
        agent_id:
          type: string
          example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
          description: Corresponding chat agent id of this chat.
        version:
          type:
          - integer
          - 'null'
          example: 1
          description: The version of the agent
        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 chat. Only available after the chat ends.
        chat_status:
          type: string
          enum:
          - ongoing
          - ended
          - error
          example: ongoing
          description: 'Status of chat.


            - `ongoing`: Chat session is ongoing, chat agent can receive new message and generate response.

            - `ended`: Chat session has ended, and no longer can generate new response.

            - `error`: Chat encountered error.

            '
        chat_type:
          type: string
          enum:
          - api_chat
          - sms_chat
          example: api_chat
          description: Type of the chat
        custom_attributes:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: number
            - type: boolean
          description: Custom attributes for the chat
        start_timestamp:
          type: integer
          example: 1703302407333
          description: Begin timestamp (milliseconds since epoch) of the chat. Available after chat starts.
        end_timestamp:
          type:
          - integer
          - 'null'
          example: 1703302428855
          description: End timestamp (milliseconds since epoch) of the chat. Available after chat 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 chat.
        message_with_tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/MessageOrToolCall'
          description: Transcript of the chat weaved with tool call invocation and results.
        metadata:
          type: object
          description: An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the chat. Not used for processing. You can later get this field from the chat object.
        chat_cost:
          type: object
          properties:
            product_costs:
              type: array
              description: List of products with their unit prices and costs in cents
              items:
                $ref: '#/components/schemas/ProductCost'
            combined_cost:
              type: number
              description: Combined cost of all individual costs in cents
              example: 70
        chat_analysis:
          description: Post chat analysis that includes information such as sentiment, status, summary, and custom defined data to extract. Available after chat ends. Subscribe to `chat_analyzed` webhook event type to receive it once ready.
          $ref: '#/components/schemas/ChatAnalysis'
    MessageOrToolCall:
      oneOf:
      - $ref: '#/components/schemas/Message'
      - $ref: '#/components/schemas/ToolCallInvocationMessage'
      - $ref: '#/components/schemas/ToolCallResultMessage'
      - $ref: '#/components/schemas/NodeTransitionMessage'
      - $ref: '#/components/schemas/StateTransitionMessage'
    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.
    NodeTransitionMessageBase:
      type: object
      required:
      - role
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        role:
          type: string
          enum:
          - node_transition
          description: This is 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.
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
    V3ChatResponse:
      allOf:
      - $ref: '#/components/schemas/ChatResponse'
      - type: object
        description: V3 list chats response. Transcript fields are intentionally omitted.
        not:
          anyOf:
          - required:
            - transcript
          - required:
            - message_with_tool_calls
          - required:
            - scrubbed_message_with_tool_calls
    MessageBase:
      type: object
      required:
      - role
      - content
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        role:
          type: string
          enum:
          - agent
          - user
          description: Documents whether this message is sent by agent or user.
          example: agent
        content:
          type: string
          description: Content of the message
          example: hi how are you doing?
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
    StateTransitionMessage:
      allOf:
      - $ref: '#/components/schemas/StateTransitionMessageBase'
      - required:
        - message_id
        - created_timestamp
    ChatAnalysis:
      type: object
      properties:
        chat_summary:
          type: string
          example: The agent messages 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 chat.
        user_sentiment:
          type: string
          enum:
          - Negative
          - Positive
          - Neutral
          - Unknown
          example: Positive
          description: Sentiment of the user in the chat.
        chat_successful:
          type: boolean
          example: true
          description: Whether the agent seems to have a successful chat 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 chat agent post chat analysis data. Can be empty if nothing is specified.
    Message:
      allOf:
      - $ref: '#/components/schemas/MessageBase'
      - required:
        - message_id
        - created_timestamp
    ToolCallResultMessageBase:
      type: object
      required:
      - role
      - tool_call_id
      - content
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        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.
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
    NodeTransitionMessage:
      allOf:
      - $ref: '#/components/schemas/NodeTransitionMessageBase'
      - required:
        - message_id
        - created_timestamp
    ToolCallInvocationMessage:
      allOf:
      - $ref: '#/components/schemas/ToolCallInvocationMessageBase'
      - required:
        - message_id
        - created_timestamp
    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.
    ToolCallResultMessage:
      allOf:
      - $ref: '#/components/schemas/ToolCallResultMessageBase'
      - required:
        - message_id
        - created_timestamp
    ToolCallInvocationMessageBase:
      type: object
      required:
      - role
      - tool_call_id
      - name
      - arguments
      properties:
        message_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the message
        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.
        created_timestamp:
          type: integer
          description: Create timestamp of the message
          example: 1703302428855
  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.
    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.
    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.
    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.
  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"