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

# List calls

> Retrieve a paginated list of calls for your account.

Returns call details including transcript, recording URL, summary, billing information, customer-supplied metadata, and analysis.
For account and internal-tracking fields (e.g. `account_id`, `external_call_id`, `completed`), use `GET /v1/calls/{call_id}`.




## OpenAPI

````yaml /api-reference/openapi.json get /v1/calls
openapi: 3.0.3
info:
  title: TopCalls Voice API
  description: >
    TopCalls Voice Gateway API for creating and managing AI-powered phone calls.


    ## Authentication


    All API requests require authentication. Include your API key in the
    `Authorization` header:


    ```

    Authorization: Bearer tc_live_xxxxx

    ```


    ## Rate Limits


    Direct call creation via `POST /v1/calls` is limited to your account's

    `max_calls_per_minute` setting (default: 20) per minute. Exceeding it
    returns

    `429 Too Many Requests` with a `Retry-After` header.

    All endpoints are additionally subject to a flat limit of 120 requests per

    minute per account (all methods).


    On a `429`, wait for the number of seconds in the `Retry-After` header, then

    retry the same request. For automated clients, back off progressively on

    repeated `429`s. Limits are per account and are shared by all API keys.


    ## Error Format


    All errors follow RFC 7807 Problem+JSON format:


    ```json

    {
      "type": "https://api.topcalls.ai/errors/insufficient_quota",
      "title": "Insufficient Quota",
      "status": 402,
      "detail": "You need 5 minutes but have 3.5 remaining"
    }

    ```
  version: 1.0.0
  contact:
    name: TopCalls Support
    url: https://topcalls.ai
  license:
    name: Proprietary
servers:
  - url: https://api.topcalls.ai
    description: Production
security: []
tags:
  - name: Calls
    description: Create and manage phone calls
  - name: Phone Numbers
    description: Manage phone numbers and carriers
  - name: Account
    description: Account information and usage
  - name: Webhooks
    description: Webhook configuration and events
  - name: Configuration
    description: Available AI models, voices, and platform capabilities
paths:
  /v1/calls:
    get:
      tags:
        - Calls
      summary: List calls
      description: >
        Retrieve a paginated list of calls for your account.


        Returns call details including transcript, recording URL, summary,
        billing information, customer-supplied metadata, and analysis.

        For account and internal-tracking fields (e.g. `account_id`,
        `external_call_id`, `completed`), use `GET /v1/calls/{call_id}`.
      operationId: listCalls
      parameters:
        - name: limit
          in: query
          description: Maximum number of results (1-200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: cursor
          in: query
          description: Pagination cursor (ISO 8601 timestamp)
          schema:
            type: string
            format: date-time
        - name: status
          in: query
          description: |
            Filter by call telephony outcome. Targets the `call_status` column.
          schema:
            type: string
            enum:
              - completed
              - no-answer
              - failed
              - busy
              - dispatch_timeout
        - name: campaign_id
          in: query
          description: Filter by campaign id.
          schema:
            type: string
            format: uuid
        - name: phone_number
          in: query
          description: Filter by destination phone number (exact match, E.164 format).
          schema:
            type: string
        - name: from_phone_number
          in: query
          description: Filter by caller ID used (exact match, E.164 format).
          schema:
            type: string
        - name: answered_by
          in: query
          description: Filter by who answered the call.
          schema:
            type: string
            enum:
              - human
              - voicemail
              - ivr
              - unknown
        - name: disposition
          in: query
          description: >-
            Filter by call disposition/outcome (exact match, e.g. "confirmed",
            "interested", "no_answer").
          schema:
            type: string
        - name: lead_id
          in: query
          description: Filter by lead id.
          schema:
            type: string
            format: uuid
        - name: created_after
          in: query
          description: Only return calls created at or after this timestamp.
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          description: Only return calls created at or before this timestamp.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: List of calls
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCallsResponse'
              example:
                data:
                  - id: 564d4fd4-03bc-400a-abe0-05540fbeff88
                    created_at: '2025-12-22T10:30:00Z'
                    phone_number: '+14155551234'
                    from_phone_number: '+18005551234'
                    status: completed
                    call_status: completed
                    duration: 2.5
                    started_at: '2025-12-22T10:30:05Z'
                    end_at: '2025-12-22T10:32:35Z'
                    campaign_id: null
                    lead_id: null
                    answered_by: human
                    error_message: null
                    recording_url: https://api.example.com/recordings/2025/12/22/mp3
                    transcript:
                      - id: 1
                        user: assistant
                        text: Hi, this is Rachel from TopView Dental...
                        created_at: '2025-12-22T10:30:05Z'
                    call_summary: Successfully confirmed appointment...
                    disposition: confirmed
                    actual_duration_billed: 2.5
                    metadata:
                      patient_id: pat_123
                    analysis: null
                next_cursor: '2025-12-22T10:29:00Z'
        '400':
          description: >-
            Invalid filter value (e.g. `answered_by` not in the allowed enum,
            `lead_id` not a UUID)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - bearerAuth: []
components:
  schemas:
    ListCallsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CallListItem'
          description: Array of call objects with essential fields only
        next_cursor:
          type: string
          format: date-time
          nullable: true
          description: Pagination cursor for next page (ISO 8601 timestamp)
    Problem:
      type: object
      required:
        - status
        - title
      properties:
        type:
          type: string
          format: uri
          description: Error type URI
        title:
          type: string
          description: Error title
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable error detail
        code:
          type: string
          description: >
            Machine-readable error code for programmatic handling. Present on

            errors that carry a stable identifier (e.g. `PROMPT_SAFETY_FRAUD`,

            `job_not_found`, `too_many_ids`, `no_matches`). Distinct from the

            per-field `errors[].code` used for validation failures. Scenario-

            specific — see each endpoint's response examples for the exact
            value.
        instance:
          type: string
          format: uuid
          description: Request instance ID
        errors:
          type: array
          description: Validation errors (for 400 responses)
          items:
            type: object
            properties:
              path:
                type: string
                description: Field path (e.g., "phone_number", "metadata.from_number")
              message:
                type: string
                description: Error message
              code:
                type: string
                description: Error code (e.g., "invalid_string", "custom")
        details:
          type: string
          description: Additional error details (for provider errors)
    CallListItem:
      type: object
      description: >
        Call object returned in list view.

        Includes transcript, recording URL, summary, billing information,
        customer-supplied metadata, and analysis.

        For account and internal-tracking fields (e.g. `account_id`,
        `external_call_id`, `completed`), use GET /v1/calls/{call_id}.
      properties:
        id:
          type: string
          format: uuid
          description: Call UUID
        created_at:
          type: string
          format: date-time
          description: When call was created
        phone_number:
          type: string
          nullable: true
          description: Destination phone number (E.164 format)
          example: '+14155551234'
        from_phone_number:
          type: string
          nullable: true
          description: Caller ID used (E.164 format)
          example: '+18005551234'
        status:
          type: string
          enum:
            - pending
            - queued
            - in_progress
            - completed
            - failed
            - cancelled
          description: Gateway execution status
        call_status:
          type: string
          nullable: true
          description: >-
            Telephony outcome (in-progress, completed, failed, no-answer, busy,
            rejected, cancelled)
        duration:
          type: number
          nullable: true
          description: Call duration in minutes
          example: 2.5
        started_at:
          type: string
          format: date-time
          nullable: true
          description: When call started
        end_at:
          type: string
          format: date-time
          nullable: true
          description: When call ended
        campaign_id:
          type: string
          format: uuid
          nullable: true
          description: Campaign UUID (if campaign call)
        lead_id:
          type: string
          format: uuid
          nullable: true
          description: Lead UUID (if campaign call)
        answered_by:
          type: string
          nullable: true
          enum:
            - human
            - voicemail
            - ivr
            - unknown
          description: Who answered the call
        error_message:
          type: string
          nullable: true
          description: Error message if call failed
        recording_url:
          type: string
          nullable: true
          format: uri
          description: Recording URL (available ~15 seconds after call ends)
          example: https://api.example.com/recordings/2025/12/22/mp3
        transcript:
          type: array
          nullable: true
          description: Call transcript (JSONB array)
          items:
            type: object
            properties:
              id:
                type: integer
                description: Sequential message ID
              user:
                type: string
                enum:
                  - user
                  - assistant
                description: Speaker (user = human, assistant = AI)
              text:
                type: string
                description: Transcribed text
              created_at:
                type: string
                format: date-time
                description: Timestamp
        call_summary:
          type: string
          nullable: true
          description: AI-generated call summary
        disposition:
          type: string
          nullable: true
          description: >-
            Call disposition/outcome label as defined by the campaign's analysis
            schema (e.g., "Appointment Booked", "Not Converted", "Voicemail")
        actual_duration_billed:
          type: number
          nullable: true
          description: Actual duration billed in minutes
          example: 2.5
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Customer-supplied keys only (fields you passed at call creation, or
            via lead metadata). Internal gateway/provider configuration is never
            included.
        analysis:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            AI-generated structured analysis of the call, if analysis was
            requested for this call. Null when no analysis was produced.
  responses:
    Unauthorized:
      description: Unauthorized (missing or invalid API key)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 401
            title: Unauthorized
            detail: Invalid or missing API key
    Forbidden:
      description: Forbidden (missing required scope)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 403
            title: Forbidden
            detail: 'Missing required scope: calls:write'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Use `Authorization: Bearer tc_live_xxxxx`

````