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

# List Calls

> Returns a paginated list of calls for your account, most recent first. Combine the query parameters to narrow the result set — they mirror the filters available in the dashboard's Conversations view.



## OpenAPI

````yaml GET /v1/calls
openapi: 3.1.0
info:
  title: OSVI AI API
  description: REST API for the OSVI AI voice and chat platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.osvi.ai
security:
  - ApiToken: []
paths:
  /v1/calls:
    get:
      summary: List calls
      description: >-
        Returns a paginated list of calls for your account, most recent first.
        Combine the query parameters to narrow the result set — they mirror the
        filters available in the dashboard's Conversations view.
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by outcome. Accepts a single value or a comma-separated list.
          schema:
            type: string
            enum:
              - picked
              - not_picked
              - failed
              - busy
              - voicemail
              - in_progress
          example: picked
        - name: agent_uuid
          in: query
          required: false
          description: >-
            Only calls handled by this agent. Returns `404` if the agent is not
            on your account.
          schema:
            type: string
          example: agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og
        - name: campaign_id
          in: query
          required: false
          schema:
            type: integer
          example: 7
        - name: campaign_upload_id
          in: query
          required: false
          description: Only calls from a specific contact upload within a campaign.
          schema:
            type: integer
          example: 19
        - name: phone_number
          in: query
          required: false
          description: Partial match on the other party's number.
          schema:
            type: string
          example: '9876543210'
        - name: call_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - inbound
              - outbound
          example: outbound
        - name: start_date
          in: query
          required: false
          description: >-
            Inclusive lower bound on `call_picked_at`. Accepts a date
            (`2026-06-01`, interpreted in IST) or a full ISO-8601 timestamp.
          schema:
            type: string
          example: '2026-06-01'
        - name: end_date
          in: query
          required: false
          description: Inclusive upper bound on `call_picked_at`.
          schema:
            type: string
          example: '2026-06-30'
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          required: false
          description: Results per page (max 100).
          schema:
            type: integer
            default: 25
          example: 25
      responses:
        '200':
          description: Paginated list of calls.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/V1CallSummary'
                  meta:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: The `agent_uuid` filter does not match an agent on your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
              example:
                success: false
                error: agent_not_found
                details: null
components:
  schemas:
    V1CallSummary:
      type: object
      properties:
        call_id:
          type: string
          format: uuid
          example: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
        agent_uuid:
          type: string
          example: agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og
        agent_name:
          type: string
          example: Appointment Reminder
        phone_number:
          type: string
          description: >-
            The other party's number (the contact for outbound, the caller for
            inbound).
          example: '+919876543210'
        from_number:
          type: string
          nullable: true
          description: The number the call was placed from / received on.
          example: '+911140001234'
        status:
          type: string
          enum:
            - picked
            - not_picked
            - failed
            - busy
            - voicemail
            - in_progress
          example: picked
        call_type:
          type: string
          nullable: true
          enum:
            - inbound
            - outbound
            - null
          example: outbound
        duration_seconds:
          type: integer
          nullable: true
          description: Talk time in seconds, or `null` for calls that were never answered.
          example: 42
        call_ended_by:
          type: string
          nullable: true
          enum:
            - agent
            - user
            - null
          example: agent
        call_ended_reason:
          type: string
          nullable: true
          example: assistant-ended-call
        campaign_id:
          type: integer
          nullable: true
          example: 7
        campaign_upload_id:
          type: integer
          nullable: true
          example: 19
        tag:
          $ref: '#/components/schemas/V1Tag'
        created_at:
          type: string
          format: date-time
          example: '2026-06-12T09:30:00+05:30'
        call_picked_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-06-12T09:30:04+05:30'
    Pagination:
      type: object
      description: Pagination metadata. `per_page` is capped at 100.
      properties:
        current_page:
          type: integer
          example: 1
        total_pages:
          type: integer
          example: 4
        total_count:
          type: integer
          example: 87
        per_page:
          type: integer
          example: 25
    ErrorUnauthorized:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Invalid API token
    ErrorNotFound:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: agent_not_found
        details:
          type: object
          nullable: true
          example: null
    V1Tag:
      type: object
      nullable: true
      description: >-
        The tag applied to the call by post-call analysis, or `null` if
        untagged.
      properties:
        id:
          type: integer
          example: 12
        name:
          type: string
          example: interested
        color_code:
          type: string
          example: '#22c55e'
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: API-Token
      description: >-
        16-character API token associated with your OSVI account. Find it in
        your dashboard under Settings → API.

````