List custom voices via the xAI API

Inventory every custom voice your team owns when you need voice_id values for unary TTS, streaming TTS, or Speech-to-Speech and you refuse to hunt cards in the console one by one. Official Custom Voices documents GET https://api.x.ai/v1/custom-voices with Bearer API-key auth, optional limit (default 100, range 1–1000) and pagination_token for later pages. The response returns a voices array of metadata objects plus a nullable pagination_token. Custom clones never appear on GET /v1/tts/voices; that list stays built-in only, which is why this dedicated GET exists after you create voices with Create a custom voice.

What you need

An xAI API key for the team that owns the clones, and at least one custom voice created in the console (free up to 30) or via Enterprise POST /v1/custom-voices. Custom Voices availability is United States only, except Illinois, per the same docs. Neighboring voice jobs include Convert text to speech with the Grok Voice API, Pick built-in voices for the Grok Voice API, and Update custom voice metadata via the xAI API. More voice jobs live on the Voice hub.

Page through team custom voices

1. Export the inference API key outside of source control:

export XAI_API_KEY="your_api_key"

2. Request the first page (raise limit when you expect more than the default hundred):

curl -s "https://api.x.ai/v1/custom-voices?limit=50" \
  -H "Authorization: Bearer ${XAI_API_KEY}"

3. Read each object's voice_id (eight lowercase alphanumeric characters), name, labels such as tone / use_case, and created_at. Pass a returned voice_id straight into POST /v1/tts as voice_id, into the streaming TTS voice query param, or into Speech-to-Speech session.voice.

4. When pagination_token is non-null, request the next page with the same limit and that token:

curl -s "https://api.x.ai/v1/custom-voices?limit=50&pagination_token=${TOKEN}" \
  -H "Authorization: Bearer ${XAI_API_KEY}"

5. Stop when pagination_token is null. Keep this inventory on https://api.x.ai; Management API billing hosts will not serve custom-voice routes.

Pair with create, update, and delete

Use this GET after console create or Enterprise POST so automation never guesses ids from display names alone. Pair with Update custom voice metadata via the xAI API when labels need a PATCH without re-recording audio, and with Delete a custom voice via the xAI API when you must free a slot under the thirty-voice team cap before the next clone.

Pitfalls

Expecting custom clones inside GET /v1/tts/voices returns only built-ins and looks like the team has zero clones. Calling list with a key from the wrong team returns that other team's empty or unrelated set because voices are team-scoped. Ignoring a non-null pagination_token silently drops voices past the first page when a team approaches the cap.