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

# List Voice Clones

> Retrieve all voice clones for the authenticated user

Retrieve a list of all voice clones associated with your account, including their training status, settings, and usage statistics.

<Note>Requires the `voice:read` permission.</Note>

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key that has `voice:read` permission (e.g., "Bearer
  bna-your-api-key")
</ParamField>

### Query Parameters

<ParamField query="status" type="string">
  Filter by training status: `processing`, `ready`, `failed`
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of voice clones to return (1-100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset
</ParamField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.buena.ai/api/v2/voice-clones" \
    -H "Authorization: Bearer bna-your-api-key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.buena.ai/api/v2/voice-clones", {
    headers: {
      Authorization: "Bearer bna-your-api-key",
    },
  });

  const data = await response.json();
  console.log(data.data.voiceClones);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.buena.ai/api/v2/voice-clones',
      headers={'Authorization': 'Bearer bna-your-api-key'}
  )

  data = response.json()
  for voice in data['data']['voiceClones']:
      print(f"Voice: {voice['name']} - ID: {voice['voiceId']}")
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Always `true` for successful requests
</ResponseField>

<ResponseField name="data" type="object">
  Voice clones data object

  <Expandable title="Voice Clones Data">
    <ResponseField name="voiceClones" type="array">
      Array of voice clone objects

      <Expandable title="Voice Clone Object">
        <ResponseField name="voiceId" type="string">
          Unique voice clone identifier (voiceId)
        </ResponseField>

        <ResponseField name="name" type="string">
          User-defined name for the voice clone
        </ResponseField>

        <ResponseField name="description" type="string">
          Description of the voice clone
        </ResponseField>

        <ResponseField name="isActive" type="boolean">
          Whether the voice clone is active and available for use
        </ResponseField>

        <ResponseField name="sampleCount" type="number">
          Number of audio samples used to train this voice
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          ISO 8601 timestamp when created
        </ResponseField>

        <ResponseField name="updatedAt" type="string">
          ISO 8601 timestamp when last updated
        </ResponseField>

        <ResponseField name="labels" type="object">
          Metadata labels associated with the voice clone
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of voice clones for the user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "voiceClones": [
        {
          "voiceId": "pNInz6obpgDQGcFmaJgB",
          "name": "Professional Voice",
          "description": "Professional outreach voice for LinkedIn",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "updatedAt": "2024-01-19T14:30:00.000Z",
          "isActive": true,
          "sampleCount": 3,
          "labels": {
            "userId": "user123",
            "createdAt": "2024-01-15T10:30:00.000Z"
          }
        },
        {
          "voiceId": "2EiwWnXFnvU5JabPnv8n",
          "name": "Sales Voice",
          "description": "Energetic sales voice for cold outreach",
          "createdAt": "2024-01-20T08:15:00.000Z",
          "updatedAt": "2024-01-20T08:15:00.000Z",
          "isActive": true,
          "sampleCount": 2,
          "labels": {
            "userId": "user123",
            "createdAt": "2024-01-20T08:15:00.000Z"
          }
        }
      ],
      "total": 2
    }
  }
  ```
</ResponseExample>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Voice Clone" icon="plus" href="/api-reference/voice/create-clone">
    Create a new voice clone
  </Card>

  <Card title="Generate Preview" icon="play" href="/api-reference/voice/generate-preview">
    Test your voice clone
  </Card>

  <Card title="Update Settings" icon="edit" href="/api-reference/voice/update-clone">
    Modify voice clone settings
  </Card>

  <Card title="Delete Voice Clone" icon="trash" href="/api-reference/voice/delete-clone">
    Remove a voice clone
  </Card>
</CardGroup>

{" "}