Search Voices

List and search available voices with filtering and pagination

Overview

The voices.search() method retrieves a list of all available voices for a user with support for search, filtering, sorting, and pagination.

Method Signature

client.voices.search(
    next_page_token: Optional[str] = None,
    page_size: Optional[int] = None,
    search: Optional[str] = None,
    sort: Optional[str] = None,
    sort_direction: Optional[str] = None,
    voice_type: Optional[str] = None,
    category: Optional[str] = None,
    fine_tuning_state: Optional[str] = None,
    collection_id: Optional[str] = None,
    include_total_count: Optional[bool] = None,
    voice_ids: Optional[Union[str, Sequence[str]]] = None,
    request_options: Optional[RequestOptions] = None
) -> GetVoicesV2Response

Parameters

Returns

GetVoicesV2Response · object

Response containing the list of voices and pagination information.

Show Response Fields

voices · List[Voice] · required

The list of voices matching the query. Each voice contains:

• voice_id - The ID of the voice
• name - The name of the voice
• category - The category of the voice
• description - Description of the voice
• labels - Labels associated with the voice
• preview_url - URL to preview the voice
• settings - Voice settings configuration
• Additional metadata fields

has_more · bool · required

Indicates whether there are more voices available in subsequent pages. Use this flag (and next_page_token) for reliable pagination instead of relying on total_count.

total_count · int · required

The total count of voices matching the query. This is a live snapshot and may change between requests.

next_page_token · str

Token to retrieve the next page of results. Pass this value to the next request to continue pagination. Returns None if there are no more results.

Examples

Basic Search

Search for all available voices:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.voices.search()
print(f"Found {len(response.voices)} voices")
for voice in response.voices:
    print(f"- {voice.name} ({voice.voice_id})")

Search with Filters

Search for cloned voices with pagination:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.voices.search(
    category="cloned",
    page_size=20,
    sort="created_at_unix",
    sort_direction="desc"
)

print(f"Found {response.total_count} cloned voices")
for voice in response.voices:
    print(f"- {voice.name}: {voice.description}")

Search by Text

Search for voices matching a specific term:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.voices.search(
    search="british accent",
    voice_type="default"
)

for voice in response.voices:
    print(f"Found: {voice.name}")
    if voice.labels:
        print(f"  Labels: {voice.labels}")

Pagination

Iterate through all voices using pagination:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

all_voices = []
next_token = None

while True:
    response = client.voices.search(
        next_page_token=next_token,
        page_size=100
    )
    
    all_voices.extend(response.voices)
    
    if not response.has_more:
        break
    
    next_token = response.next_page_token

print(f"Retrieved {len(all_voices)} total voices")

Filter by Voice IDs

Retrieve specific voices by their IDs:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

voice_ids = [
    "21m00Tcm4TlvDq8ikWAM",
    "AZnzlk1XvdvUeBnXmlld",
    "EXAVITQu4vr4xnSDxMaL"
]

response = client.voices.search(voice_ids=voice_ids)

for voice in response.voices:
    print(f"{voice.voice_id}: {voice.name}")

Related Methods

• Get Voice - Retrieve metadata for a specific voice
• Clone Voice - Create an instant voice clone
• Voice Settings - Manage voice settings