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

# List External Call Recordings with the API

> List and paginate external call sessions, with filters for locating uploaded recordings and their processed call data.

Each item represents one external call session. A session may contain multiple recording legs when a provider splits a call around holds or transfers.

Learn how Simple AI represents call data in the [AI phone calls guide](/calls).

The `started_at` field is the earliest visible recording-leg start. Date filters apply to that value rather than the time the recording was imported.


## OpenAPI

````yaml GET /external_calls
openapi: 3.1.0
info:
  title: Public API v1
  description: >-
    Public API v1 requiring API keys.


    **Timestamps:** All datetime fields in API responses are returned in UTC
    using ISO 8601 format (e.g., `2024-01-15T14:30:00Z`). When filtering by date
    parameters, provide timestamps in ISO 8601 format.
  version: 0.1.0
servers:
  - url: https://api.usesimple.ai/api/v1
    description: Production API Server
security: []
paths:
  /external_calls:
    get:
      tags:
        - External Calls
      summary: List External Calls
      description: >-
        List external calls associated with the API key's account. Each result
        represents one call session and may contain one or more recording legs.
      operationId: list_external_calls
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: source_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - processing
              - transcribed
              - error
        - name: created_at_gte
          in: query
          required: false
          description: Return calls that started at or after this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
        - name: created_at_lte
          in: query
          required: false
          description: Return calls that started at or before this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
        - name: updated_at_gte
          in: query
          required: false
          description: >-
            Return calls last updated at or after this ISO 8601 timestamp
            (inclusive).
          schema:
            type: string
            format: date-time
        - name: updated_at_lte
          in: query
          required: false
          description: >-
            Return calls last updated at or before this ISO 8601 timestamp
            (inclusive).
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: External calls returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalCallListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    ExternalCallListResponse:
      type: object
      required:
        - external_calls
        - total_count
        - page
        - page_size
        - total_pages
      properties:
        external_calls:
          type: array
          items:
            $ref: '#/components/schemas/ExternalCallSummary'
        total_count:
          type: integer
          minimum: 0
        page:
          type: integer
          minimum: 1
        page_size:
          type: integer
          minimum: 1
          maximum: 100
        total_pages:
          type: integer
          minimum: 0
      title: External Call List Response
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ExternalCallSummary:
      type: object
      required:
        - id
        - external_call_id
        - title
        - direction
        - from_number
        - to_number
        - duration_seconds
        - started_at
        - status
        - recording_count
        - source
        - created_at
        - updated_at
        - recording_presigned_urls
      properties:
        id:
          type: string
          format: uuid
        external_call_id:
          type: string
        title:
          anyOf:
            - type: string
            - type: 'null'
        direction:
          anyOf:
            - type: string
              enum:
                - inbound
                - outbound
            - type: 'null'
        from_number:
          anyOf:
            - type: string
            - type: 'null'
        to_number:
          anyOf:
            - type: string
            - type: 'null'
        duration_seconds:
          anyOf:
            - type: integer
            - type: 'null'
        started_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - processing
            - transcribed
            - error
        recording_count:
          type: integer
          minimum: 0
        source:
          anyOf:
            - $ref: '#/components/schemas/ExternalCallSource'
            - type: 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        recording_presigned_urls:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Presigned URLs for all playable recordings in chronological order.
            External calls can have multiple recordings per session. URLs expire
            after one hour. Deleted, excluded, and recordings awaiting required
            audio redaction are omitted; an empty array means no recordings are
            currently playable. If URL signing fails for a recording, its URL is
            omitted and the call data is still returned.
      title: External Call Summary
    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
    ExternalCallSource:
      type: object
      required:
        - id
        - name
        - provider
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        provider:
          type: string
      title: External Call Source
  securitySchemes:
    APIKeyHeader:
      type: http
      scheme: bearer
      description: 'Your API key, sent as `Authorization: Bearer YOUR_API_KEY`'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.