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

# Search custom voices

> **Searches and retrieves voices registered by the customer based on specified criteria.**

You can filter customer registered voices available in your account by various conditions such as name, language, style, etc.

### Endpoint

```http theme={"dark"}
https://supertoneapi.com/v1/custom-voices/search
```

### Key Parameters

| Parameter     | Description                           | Example                 |
| :------------ | :------------------------------------ | :---------------------- |
| `name`        | Search by voice name (partial match)  | `My cloned voice 1`     |
| `description` | Search by description (partial match) | `kind and gentle`, etc. |


## OpenAPI

````yaml openapi.json get /v1/custom-voices/search
openapi: 3.0.0
info:
  title: Supertone Public API
  description: >-
    Supertone API is a RESTful API for using our state-of-the-art AI voice
    models.
  version: 0.9.0
  contact: {}
servers:
  - url: https://supertoneapi.com
    description: Production
security: []
tags:
  - name: voices
    description: Voice Library API endpoints
  - name: custom_voices
    description: Custom Voice Management API endpoints
  - name: text_to_speech
    description: Text-to-Speech API endpoints
  - name: usage
    description: Usage Analytics API endpoints
paths:
  /v1/custom-voices/search:
    get:
      tags:
        - custom_voices
      summary: Search custom (cloned) voices
      description: >-
        Search and filter custom (cloned) voices based on various parameters.
        Space-separated terms in name/description fields use AND condition (all
        terms must be present).
      operationId: search_custom_voices
      parameters:
        - name: page_size
          required: false
          in: query
          description: 'Number of items per page (default: 20, min: 10, max: 100)'
          schema:
            type: number
        - name: next_page_token
          required: false
          in: query
          description: Token for pagination (obtained from the previous page's response)
          schema:
            type: string
        - name: name
          required: false
          in: query
          description: Search across name. Space separated.
          schema:
            type: string
        - name: description
          required: false
          in: query
          description: Search across description. Space separated.
          schema:
            type: string
      responses:
        '200':
          description: Paginated custom voices search response with next page token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomVoiceListResponse'
        '401':
          description: 'Unauthorized: Invalid API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '404':
          description: 'Not Found: No custom voices found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: 'Internal Server Error: Failed to search custom voices'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - api-key: []
components:
  schemas:
    GetCustomVoiceListResponse:
      type: object
      properties:
        items:
          description: List of custom voice items
          type: array
          items:
            $ref: '#/components/schemas/GetCustomVoiceResponse'
        total:
          type: number
          description: Total number of available custom voices
          example: 25
        next_page_token:
          type: string
          description: >-
            Token for fetching the next page of results. A valid non-negative
            integer string (e.g., "10", "20"). Null if no more pages.
          example: '10'
      required:
        - items
        - total
    UnauthorizedErrorResponse:
      type: object
      properties:
        status:
          type: string
          description: Response status
          example: error
        message:
          description: Unauthorized error details
          example:
            message: Invalid API Key
            error: Unauthorized
            statusCode: 401
          allOf:
            - $ref: '#/components/schemas/ErrorMessageData'
      required:
        - status
        - message
    NotFoundErrorResponse:
      type: object
      properties:
        status:
          type: string
          description: Response status
          example: error
        message:
          description: Not found error details
          example:
            message: Voice not found
            error: Not Found
            statusCode: 404
          allOf:
            - $ref: '#/components/schemas/ErrorMessageData'
      required:
        - status
        - message
    InternalServerErrorResponse:
      type: object
      properties:
        status:
          type: string
          description: Response status
          example: error
        message:
          description: Internal server error details
          example:
            message: Failed to convert text to speech
            error: Internal Server Error
            statusCode: 500
          allOf:
            - $ref: '#/components/schemas/ErrorMessageData'
      required:
        - status
        - message
    GetCustomVoiceResponse:
      type: object
      properties:
        voice_id:
          type: string
          description: Unique identifier for the voice
          example: voice_123456789
        name:
          type: string
          description: Name of the voice
          example: My Custom Voice
        description:
          type: string
          description: Description of the voice
          example: A warm and friendly voice for customer service
      required:
        - voice_id
        - name
        - description
    ErrorMessageData:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Invalid API Key
        error:
          type: string
          description: Error type
          example: Unauthorized
        status_code:
          type: number
          description: HTTP status code
          example: 401
      required:
        - message
        - error
        - status_code
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-sup-api-key

````