# List cloned voices (/docs/api-reference/voice-cloning/listClonedVoices)

> Your cloned voices, oldest first, one cursor page at a time. Call it with no cursor, then pass back the next_cursor you were handed until it is null.

**GET** `/voices`

Your cloned voices, oldest first, one cursor page at a time. Call it with
no `cursor`, then pass back the `next_cursor` you were handed until it is
`null`.

Once a voice is `ready`, its `voice_id` is the provider voice id to put
in an agent's `voice.voice_id` with `voice.provider: cartesia`.

```yaml
operationId: listClonedVoices
parameters:
  - in: query
    name: limit
    schema:
      type: integer
      default: 20
      maximum: 100
    description: Rows per page. Above 100 the request is refused.
  - in: query
    name: cursor
    schema:
      type: string
    description: |
      The `next_cursor` from your previous response. Omit it on the first
      request. Opaque: pass it back unchanged.
responses:
  '200':
    description: One page of cloned voices, oldest first.
    content:
      application/json:
        schema:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                description: |
                  A voice cloned from an audio sample. Created asynchronously: `status` is
                  `processing` until the provider finishes, then `ready` or `failed`.
                  `voice_id` is the provider id an agent uses, and is `null` until ready.
                properties:
                  id:
                    type: integer
                    example: 412
                  name:
                    type: string
                    example: Front desk
                  description:
                    type: string
                    nullable: true
                  language:
                    type: string
                    example: en
                  gender:
                    type: string
                    enum:
                      - male
                      - female
                  status:
                    type: string
                    enum:
                      - processing
                      - ready
                      - failed
                  voice_id:
                    type: string
                    nullable: true
                    description: |
                      The provider voice id. Put it in an agent's `voice.voice_id` with
                      `voice.provider: cartesia`. `null` until `status` is `ready`.
                    example: 8a1c2f5e-3b7d-4c9a-9f21-2e6b0d4a7c88
                  sample_url:
                    type: string
                    nullable: true
                    description: |
                      An mp3 preview of the cloned voice, when one exists. Fetching it
                      needs your API key in the `Authorization: Bearer` header, so a
                      browser `<audio>` tag cannot play it directly.
                  error:
                    type: string
                    nullable: true
                    description: |
                      Present only when `status` is `failed`. Deliberately generic: no
                      provider name and no internal detail.
                  created_at:
                    type: string
                    description: ISO 8601 time in UTC, with no offset.
                    nullable: true
                  ready_at:
                    type: string
                    description: ISO 8601 time in UTC, with no offset.
                    nullable: true
            has_more:
              type: boolean
            next_cursor:
              type: string
              nullable: true
        example:
          data:
            - id: 412
              name: Front desk
              description: null
              language: en
              gender: female
              status: ready
              voice_id: 8a1c2f5e-3b7d-4c9a-9f21-2e6b0d4a7c88
              sample_url: https://backend.omnidim.io/api/v1/voices/412/sample
              error: null
              created_at: '2026-10-12T15:18:07.424509'
              ready_at: '2026-10-12T15:18:31.009881'
          has_more: false
          next_cursor: null
  '400':
    description: |
      A bad `limit` (not 1 to 100) or an invalid `cursor`.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: |
                Stable, specific reason. Present on the newer endpoints (Voice
                cloning, WhatsApp); older endpoints return only `error`.
            request_id:
              type: string
              description: |
                Correlates this response with the server log. Present alongside
                `code`. Also sent as the `X-Request-Id` header.
        example:
          error: invalid_request
          error_description: limit must be a whole number from 1 to 100.
          code: invalid_limit
          request_id: req_5d9a1f3e8b02
  '401':
    description: Missing or invalid API key.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: |
                Stable, specific reason. Present on the newer endpoints (Voice
                cloning, WhatsApp); older endpoints return only `error`.
            request_id:
              type: string
              description: |
                Correlates this response with the server log. Present alongside
                `code`. Also sent as the `X-Request-Id` header.
        example:
          error: unauthorized
          error_description: Missing or invalid API key
          code: invalid_api_key
          request_id: req_6e2b9d4f1a38
  '403':
    description: |
      Voice cloning is not enabled for this account. It must be included in
      your plan, and your API key's user needs access to it.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: |
                Stable, specific reason. Present on the newer endpoints (Voice
                cloning, WhatsApp); older endpoints return only `error`.
            request_id:
              type: string
              description: |
                Correlates this response with the server log. Present alongside
                `code`. Also sent as the `X-Request-Id` header.
        example:
          error: forbidden
          error_description: You do not have permission to view Voice Cloning.
          code: feature_not_enabled
          request_id: req_9f2c1a4b7d3e
```

**cURL**

```bash
curl "https://backend.omnidim.io/api/v1/voices?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**curl**

```bash
curl -X GET "https://omnidim.io/api/v1/voices" \
  -H "Authorization: Bearer $OMNIDIM_API_KEY"
```