> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Calls

> Retrieve a paginated list of calls with optional filtering and sorting.

This endpoint allows querying call history with various filters including time ranges
and specific AI agents. Results are paginated for efficient data retrieval.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/calls/
openapi: 3.1.0
info:
  title: Verbex Platform API
  description: API for managing AI agents, calls, phone numbers, and more.
  version: 1.0.0
servers: []
security: []
paths:
  /v1/calls/:
    get:
      tags:
        - Calls
      summary: List Calls
      description: >-
        Retrieve a paginated list of calls with optional filtering and sorting.


        This endpoint allows querying call history with various filters
        including time ranges

        and specific AI agents. Results are paginated for efficient data
        retrieval.
      operationId: list_calls_v1_calls__get
      parameters:
        - name: ai_agent_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            title: Ai Agent Ids
        - name: batch_call_id
          in: query
          required: false
          description: >-
            Filter calls by a specific batch call ID to retrieve all calls
            associated with that batch.
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Batch Call Id
        - name: start_time_before
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Start Time Before
        - name: start_time_after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Start Time After
        - name: end_time_before
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: End Time Before
        - name: end_time_after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: End Time After
        - name: sort_direction
          in: query
          required: false
          schema:
            type: string
            pattern: ^(asc|desc)$
            default: desc
            title: Sort Direction
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            default: 100
            title: Page Size
        - name: page_token
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Page Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__calls__schemas__ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CallList:
      properties:
        calls:
          items:
            anyOf:
              - $ref: '#/components/schemas/WebCallResponse'
              - $ref: '#/components/schemas/PhoneCallResponse'
          type: array
          title: Calls
          description: List of call records, can include both web and phone calls
        next_page_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page Token
          description: Token for retrieving the next page of results in paginated responses
        total_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Count
          description: Total number of calls matching the query criteria
      type: object
      required:
        - calls
      title: CallList
    app__calls__schemas__ErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: Error code identifying the type of error that occurred
        message:
          type: string
          title: Message
          description: Human-readable description of the error
      type: object
      required:
        - error
        - message
      title: ErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WebCallResponse:
      properties:
        _id:
          type: string
          title: Id
          description: >-
            Unique identifier for the call session, automatically generated as a
            MongoDB ObjectId
        ai_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Ai Agent Id
          description: Identifier of the AI agent handling this call
        ai_agent_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Ai Agent Name
          description: Name of the AI agent handling this call
        call_status:
          type: string
          enum:
            - registered
            - ongoing
            - ended
            - error
          title: Call Status
          description: >-
            Current status of the call: 'registered' for initialized calls,
            'ongoing' for active calls, 'ended' for completed calls, 'error' for
            failed calls
        override_ai_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Override Ai Agent Id
          description: Optional identifier for an alternative AI agent handling this call
        metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Metadata
          description: Custom key-value pairs storing additional information about the call
        pia_llm_dynamic_data:
          anyOf:
            - type: object
            - type: 'null'
          title: Pia Llm Dynamic Data
          description: Dynamic data used by the AI agent during the call
        call_start_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Call Start Time
          description: Timestamp when the call was initiated, in UTC
        call_end_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Call End Time
          description: Timestamp when the call was terminated, in UTC
        messages:
          anyOf:
            - items:
                $ref: '#/components/schemas/MessageItem'
              type: array
            - type: 'null'
          title: Messages
          description: Chronological list of messages exchanged during the call
        recorded_call_audio_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Recorded Call Audio Url
          description: URL to access the recorded audio file of the call
        access_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Access Token
          description: Security token for accessing call-related resources
        call_duration_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Call Duration Seconds
          description: Duration of the call in seconds
        call_type:
          type: string
          const: web_call
          title: Call Type
          description: Indicates this response is for a web-based call
          default: web_call
        call_finish_reason:
          anyOf:
            - type: string
              enum:
                - user_ended_call
                - agent_ended_call
                - call_transferred
                - inactivity_timeout
                - maximum_duration_exceeded
                - concurrent_call_limit_reached
                - invalid_payment
                - potential_scam_detected
                - inbound_webhook_error
                - line_busy
                - call_failed
                - no_answer
                - llm_websocket_initialization_error
                - llm_websocket_connection_lost
                - llm_websocket_runtime_error
                - llm_websocket_payload_corruption
                - twilio_error
                - no_audio_input
                - speech_recognition_error
                - pia_platform_internal_error
                - unknown_error
                - user_connection_failure
            - type: 'null'
          title: Call Finish Reason
          description: Detailed reason why the web call ended, if applicable
      type: object
      required:
        - call_status
      title: WebCallResponse
    PhoneCallResponse:
      properties:
        _id:
          type: string
          title: Id
          description: >-
            Unique identifier for the call session, automatically generated as a
            MongoDB ObjectId
        ai_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Ai Agent Id
          description: Identifier of the AI agent handling this call
        ai_agent_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Ai Agent Name
          description: Name of the AI agent handling this call
        call_status:
          type: string
          enum:
            - registered
            - ongoing
            - ended
            - error
          title: Call Status
          description: >-
            Current status of the call: 'registered' for initialized calls,
            'ongoing' for active calls, 'ended' for completed calls, 'error' for
            failed calls
        override_ai_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Override Ai Agent Id
          description: Optional identifier for an alternative AI agent handling this call
        metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Metadata
          description: Custom key-value pairs storing additional information about the call
        pia_llm_dynamic_data:
          anyOf:
            - type: object
            - type: 'null'
          title: Pia Llm Dynamic Data
          description: Dynamic data used by the AI agent during the call
        call_start_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Call Start Time
          description: Timestamp when the call was initiated, in UTC
        call_end_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Call End Time
          description: Timestamp when the call was terminated, in UTC
        messages:
          anyOf:
            - items:
                $ref: '#/components/schemas/MessageItem'
              type: array
            - type: 'null'
          title: Messages
          description: Chronological list of messages exchanged during the call
        recorded_call_audio_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Recorded Call Audio Url
          description: URL to access the recorded audio file of the call
        access_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Access Token
          description: Security token for accessing call-related resources
        call_duration_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Call Duration Seconds
          description: Duration of the call in seconds
        call_type:
          type: string
          const: phone_call
          title: Call Type
          description: Indicates this response is for a telephone call
          default: phone_call
        from_number:
          type: string
          title: From Number
          description: The phone number that initiated the call (E.164 format)
        to_number:
          type: string
          title: To Number
          description: The phone number that received the call (E.164 format)
        direction:
          type: string
          enum:
            - inbound
            - outbound
          title: Direction
          description: >-
            Indicates whether the call was received by or initiated from the Pia
            Platform
        call_finish_reason:
          anyOf:
            - type: string
              enum:
                - user_ended_call
                - agent_ended_call
                - call_transferred
                - voicemail_detected
                - inactivity_timeout
                - answering_machine_detected
                - maximum_duration_exceeded
                - concurrent_call_limit_reached
                - invalid_payment
                - potential_scam_detected
                - inbound_webhook_error
                - line_busy
                - call_failed
                - no_answer
                - llm_websocket_initialization_error
                - llm_websocket_connection_lost
                - llm_websocket_runtime_error
                - llm_websocket_payload_corruption
                - frontend_payload_corruption
                - twilio_service_error
                - no_audio_input
                - speech_recognition_error
                - verbex_service_error
                - unknown_error
                - user_connection_failure
                - registered_call_timed_out
            - type: 'null'
          title: Call Finish Reason
          description: Detailed reason why the phone call ended, if applicable
      type: object
      required:
        - call_status
        - from_number
        - to_number
        - direction
      title: PhoneCallResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    MessageItem:
      properties:
        role:
          type: string
          enum:
            - agent
            - user
          title: Role
          description: >-
            Identifies whether the message is from the AI agent ('agent') or the
            human user ('user')
        content:
          type: string
          title: Content
          description: >-
            The actual text content of the message exchanged during the
            conversation
      type: object
      required:
        - role
        - content
      title: MessageItem

````