History

Manage your generated audio history

The History client provides methods to manage and retrieve your generated audio history items.

list

Returns a list of your generated audio.

client.history.list(
    page_size=100,
    start_after_history_item_id="item_123",
    voice_id="voice_id",
    model_id="model_id",
    date_before_unix=1234567890,
    date_after_unix=1234567890,
    sort_direction="desc",
    search="search term",
    source="TTS"
)

Parameters

page_size · int

How many history items to return at maximum. Cannot exceed 1000, defaults to 100.

start_after_history_item_id · str

After which ID to start fetching, use this parameter to paginate across a large collection of history items. If not provided, history items will be fetched starting from the most recently created one ordered descending by their creation date.

voice_id · str

ID of the voice to be filtered for. You can use the Get voices endpoint to list all available voices.

model_id · str

Model ID used for filtering history items.

date_before_unix · int

Unix timestamp to filter history items before this date (exclusive).

date_after_unix · int

Unix timestamp to filter history items after this date (inclusive).

sort_direction · str

Sort direction for the results. Can be “asc” or “desc”.

search · str

Search term used for filtering.

source · str

Source of the generated history item (e.g., “TTS”).

request_options · RequestOptions

Request-specific configuration.

Response

GetSpeechHistoryResponse · object

Returns a list of speech history items.

Example

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Get recent history with pagination
history = client.history.list(
    page_size=50,
    sort_direction="desc"
)

---

get

Retrieves a specific history item by ID.

client.history.get(
    history_item_id="VW7YKqPnjY4h39yTbx2L"
)

Parameters

history_item_id · str · required

ID of the history item to retrieve. You can use the list endpoint to get a list of history items.

request_options · RequestOptions

Request-specific configuration.

Response

SpeechHistoryItemResponse · object

Returns the requested history item with its metadata.

Example

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Get a specific history item
item = client.history.get(
    history_item_id="VW7YKqPnjY4h39yTbx2L"
)

---

delete

Delete a history item by its ID.

client.history.delete(
    history_item_id="VW7YKqPnjY4h39yTbx2L"
)

Parameters

history_item_id · str · required

ID of the history item to delete. You can use the list endpoint to get a list of history items.

request_options · RequestOptions

Request-specific configuration.

Response

DeleteHistoryItemResponse · object

Returns confirmation of the deletion.

Example

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Delete a history item
response = client.history.delete(
    history_item_id="VW7YKqPnjY4h39yTbx2L"
)

---

get_audio

Returns the audio of a history item.

client.history.get_audio(
    history_item_id="VW7YKqPnjY4h39yTbx2L"
)

Parameters

history_item_id · str · required

ID of the history item to retrieve audio for. You can use the list endpoint to get a list of history items.

request_options · RequestOptions

Request-specific configuration. You can pass in configuration such as chunk_size to customize the request and response.

Response

Iterator[bytes] · Iterator[bytes]

Returns the audio file of the history item as an iterator of bytes.

Example

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Get audio from a history item
audio = client.history.get_audio(
    history_item_id="VW7YKqPnjY4h39yTbx2L"
)

# Save to file
with open("output.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

---

download

Download one or more history items. If one history item ID is provided, returns a single audio file. If multiple history item IDs are provided, returns a .zip file.

client.history.download(
    history_item_ids=["item_1", "item_2"],
    output_format="mp3"
)

Parameters

history_item_ids · List[str] · required

A list of history items to download. You can get IDs of history items using the list endpoint.

output_format · str

Output format to transcode the audio file. Can be “wav” or “default”.

request_options · RequestOptions

Request-specific configuration. You can pass in configuration such as chunk_size to customize the request and response.

Response

Iterator[bytes] · Iterator[bytes]

Returns the requested audio file, or a zip file containing multiple audio files when multiple history items are requested.

Example

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Download multiple history items as a zip
audio = client.history.download(
    history_item_ids=["item_1", "item_2", "item_3"]
)

# Save to file
with open("history_items.zip", "wb") as f:
    for chunk in audio:
        f.write(chunk)

# Download a single item
audio = client.history.download(
    history_item_ids=["item_1"],
    output_format="wav"
)

---

Async Methods

All methods are also available as async methods using AsyncElevenLabs client:

import asyncio
from elevenlabs import AsyncElevenLabs

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def main():
    # List history items
    history = await client.history.list(page_size=50)
    
    # Get a specific item
    item = await client.history.get(history_item_id="VW7YKqPnjY4h39yTbx2L")
    
    # Delete an item
    await client.history.delete(history_item_id="VW7YKqPnjY4h39yTbx2L")
    
    # Get audio (async iterator)
    async for chunk in await client.history.get_audio(history_item_id="item_id"):
        # Process audio chunks
        pass
    
    # Download items (async iterator)
    async for chunk in await client.history.download(history_item_ids=["item_1"]):
        # Process download chunks
        pass

asyncio.run(main())