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

# List Voices

> Lists your [Voice](/sections/conversational-video-interface/voices) resources.

**Send `source`.** It selects which voices to return and is what makes this endpoint return Voice resources at all:

```bash
GET /v2/voices?source=user     # voices you created
GET /v2/voices?source=system   # the Tavus catalog
GET /v2/voices?source=all      # both
```

<Note>
Omitting `source` returns a legacy stock-voice listing instead: `voice_name` slugs and their linked face metadata, with `page` and `limit` echoed in the response. It carries no `voice_id` values and cannot see voices you created.
</Note>


<Info>
  For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
</Info>


## OpenAPI

````yaml get /v2/voices
openapi: 3.0.3
info:
  title: Tavus Developer API Collection
  version: 1.0.0
  contact: {}
servers:
  - url: https://tavusapi.com
security:
  - apiKey: []
tags:
  - name: Videos
  - name: Faces
  - name: Voices
  - name: Conversations
  - name: Deployments
  - name: PALs
  - name: Tools
  - name: PAL Tools
  - name: Connectors
  - name: Pronunciation Dictionaries
  - name: Replacements
  - name: Transcriptions
  - name: Documents
  - name: Memory Stores
paths:
  /v2/voices:
    get:
      tags:
        - Voices
      summary: List Voices
      description: >
        Lists your [Voice](/sections/conversational-video-interface/voices)
        resources.


        **Send `source`.** It selects which voices to return and is what makes
        this endpoint return Voice resources at all:


        ```bash

        GET /v2/voices?source=user     # voices you created

        GET /v2/voices?source=system   # the Tavus catalog

        GET /v2/voices?source=all      # both

        ```


        <Note>

        Omitting `source` returns a legacy stock-voice listing instead:
        `voice_name` slugs and their linked face metadata, with `page` and
        `limit` echoed in the response. It carries no `voice_id` values and
        cannot see voices you created.

        </Note>
      operationId: getVoices
      parameters:
        - name: source
          in: query
          description: >-
            Which voices to return. Send this to get Voice resources; omit it
            only for the legacy stock-voice listing.
          schema:
            type: string
            enum:
              - user
              - system
              - all
          example: user
        - name: limit
          in: query
          description: Page size (1–100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: page
          in: query
          description: Page number (1-based).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: sort
          in: query
          description: Sort by name, ascending or descending.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - name: search
          in: query
          description: >-
            Legacy stock-voice listing only, ignored when `source` is set.
            Case-insensitive substring match on `voice_name`.
          schema:
            type: string
        - name: tag
          in: query
          description: >-
            Legacy stock-voice listing only, ignored when `source` is set.
            Returns only voices whose face tags include this tag name
            (case-insensitive).
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Voices for the current page.
                    items:
                      $ref: '#/components/schemas/Voice'
                  total_count:
                    type: integer
                    description: Total voices matching the filters, before pagination.
                    example: 12
              examples:
                voices:
                  summary: With source set
                  value:
                    data:
                      - voice_id: v0a1b2c3d4e5f
                        voice_name: Ana
                        description: Warm, unhurried, mid-Atlantic
                        voice_type: user
                        status: completed
                        tags:
                          - support
                          - en
                        created_at: '2026-08-17T12:00:00.000000'
                    total_count: 1
                legacy:
                  summary: Without source (legacy stock-voice listing)
                  value:
                    data:
                      - voice_name: anna
                        face_id: rc9cff32ceba
                        audio_url: https://example.com/anna.mp3
                        tags:
                          - tag_name: professional
                    total_count: 40
                    page: 1
                    limit: 10
        '400':
          description: BAD REQUEST
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: source must be one of ['system', 'user', 'all']
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message.
                    example: Invalid access token
      security:
        - apiKey: []
components:
  schemas:
    Voice:
      type: object
      description: >-
        A Tavus Voice. Reference it by `voice_id`; Tavus picks the provider that
        is the best fit for the language(s) of the conversation.
      properties:
        voice_id:
          type: string
          description: >-
            Stable identifier. Use as `layers.tts.voice_id` on a PAL, or
            `default_voice_id` on a face.
          example: v0a1b2c3d4e5f
        voice_name:
          type: string
          example: Ana
        description:
          type: string
          nullable: true
          example: Warm, unhurried, mid-Atlantic
        voice_type:
          type: string
          description: '`user` for voices you created, `system` for the Tavus catalog.'
          enum:
            - user
            - system
          example: user
        status:
          type: string
          description: >-
            `started` while the voice is still being created, `completed` once
            it is ready to use, `error` if creation failed (see
            `error_message`).
          enum:
            - started
            - completed
            - error
          example: completed
        error_message:
          type: string
          description: Present only when `status` is `error`.
        tags:
          type: array
          items:
            type: string
          example:
            - support
            - en
        created_at:
          type: string
          format: date-time
          example: '2026-08-17T12:00:00.000000'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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