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

# Search Voices

> Search available voices by provider for agent voice selection.

Search provider voice catalogs used in the agent voice picker.

### Query Parameters

<ParamField query="provider" type="string" required>
  Voice provider. Supported values: `cartesia`, `elevenlabs`.
</ParamField>

<ParamField query="query" type="string">
  Free-text search term.
</ParamField>

<ParamField query="language" type="string">
  Filter by language code (for example `en`).
</ParamField>

<ParamField query="gender" type="string">
  Optional gender filter. Most relevant for Cartesia voice search.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for fetching the next page.
</ParamField>

### Response

<ResponseField name="voices" type="array">
  Matching voices.
</ResponseField>

<ResponseField name="voices[].id" type="string">
  Provider voice ID.
</ResponseField>

<ResponseField name="voices[].name" type="string">
  Voice name.
</ResponseField>

<ResponseField name="voices[].description" type="string">
  Voice description, when available.
</ResponseField>

<ResponseField name="voices[].gender" type="string|null">
  Voice gender metadata.
</ResponseField>

<ResponseField name="voices[].language" type="string|null">
  Voice language metadata.
</ResponseField>

<ResponseField name="voices[].preview_url" type="string|null">
  Direct preview URL when exposed by provider.
</ResponseField>

<ResponseField name="voices[].has_preview" type="boolean">
  Indicates whether a preview sample is available.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more results are available.
</ResponseField>

<ResponseField name="next_cursor" type="string|null">
  Cursor for the next page.
</ResponseField>

<RequestExample>
  ```http Request theme={null}
  GET /api/voices/search?provider=cartesia&query=warm&language=en&gender=feminine
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "voices": [
      {
        "id": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
        "name": "Warm Narrator",
        "description": "Conversational female voice",
        "gender": "feminine",
        "language": "en",
        "preview_url": null,
        "has_preview": true
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
  ```
</ResponseExample>