Implementation:Elevenlabs Elevenlabs python HistoryClient

Knowledge Sources	Elevenlabs_Elevenlabs_python
Domains	Audio, API_Client, History
Last Updated	2026-02-15 12:00 GMT

Overview

Concrete API client for managing speech synthesis history items provided by the ElevenLabs Python SDK.

Description

The HistoryClient wraps the ElevenLabs History API endpoints, providing access to previously generated audio items. Every text-to-speech generation is logged as a history item, and this client enables listing, retrieving, deleting, and downloading those recorded generations. The client provides five core operations:

list - Returns a paginated list of generated audio history items via GET /v1/history. Supports filtering by voice, model, date range, source, and search terms, with configurable pagination and sort direction.
get - Retrieves a single history item by ID via GET /v1/history/{history_item_id}. Returns metadata about the generation including the voice used, settings, and timestamps.
delete - Deletes a history item by ID via DELETE /v1/history/{history_item_id}.
get_audio - Streams the audio bytes of a single history item via GET /v1/history/{history_item_id}/audio. Returns an iterator of byte chunks for efficient memory usage.
download - Downloads one or more history items via POST /v1/history/download. Returns a single audio file for one item, or a .zip file containing multiple audio files when multiple IDs are provided. Supports optional output format transcoding.

Both synchronous (HistoryClient) and asynchronous (AsyncHistoryClient) variants are provided. The raw HTTP response can be accessed via the with_raw_response property.

Usage

Use this client when you need to:

Browse and search through previously generated speech audio.
Retrieve metadata about a specific text-to-speech generation.
Download the audio output from a previous generation.
Bulk-download multiple history items as a zip archive.
Clean up history by deleting individual items.

Code Reference

Source Location

Repository: Elevenlabs_Elevenlabs_python
File (high-level): src/elevenlabs/history/client.py
File (raw): src/elevenlabs/history/raw_client.py
Lines: 18-259 (HistoryClient), 262-545 (AsyncHistoryClient)

Signature

class HistoryClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper): ...

    @property
    def with_raw_response(self) -> RawHistoryClient: ...

    def list(
        self,
        *,
        page_size: typing.Optional[int] = None,
        start_after_history_item_id: typing.Optional[str] = None,
        voice_id: typing.Optional[str] = None,
        model_id: typing.Optional[str] = None,
        date_before_unix: typing.Optional[int] = None,
        date_after_unix: typing.Optional[int] = None,
        sort_direction: typing.Optional[HistoryListRequestSortDirection] = None,
        search: typing.Optional[str] = None,
        source: typing.Optional[HistoryListRequestSource] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> GetSpeechHistoryResponse: ...

    def get(
        self,
        history_item_id: str,
        *,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SpeechHistoryItemResponse: ...

    def delete(
        self,
        history_item_id: str,
        *,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DeleteHistoryItemResponse: ...

    def get_audio(
        self,
        history_item_id: str,
        *,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.Iterator[bytes]: ...

    def download(
        self,
        *,
        history_item_ids: typing.Sequence[str],
        output_format: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.Iterator[bytes]: ...

Import

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
# Access via client.history

I/O Contract

list()

Inputs

Name	Type	Required	Description
page_size	Optional[int]	No	Maximum number of history items to return. Cannot exceed 1000, defaults to 100.
start_after_history_item_id	Optional[str]	No	Cursor for pagination. Fetches items created after this history item ID.
voice_id	Optional[str]	No	Filter results by voice ID.
model_id	Optional[str]	No	Filter results by model ID. If provided, source becomes required.
date_before_unix	Optional[int]	No	Unix timestamp to filter items created before this date (exclusive).
date_after_unix	Optional[int]	No	Unix timestamp to filter items created after this date (inclusive).
sort_direction	Optional[HistoryListRequestSortDirection]	No	Sort direction for the results (e.g., 'asc' or 'desc').
search	Optional[str]	No	Search term used for filtering history items.
source	Optional[HistoryListRequestSource]	No	Source of the generated history item (e.g., 'TTS').
request_options	Optional[RequestOptions]	No	Request-specific configuration.

Output

Name	Type	Description
return	GetSpeechHistoryResponse	Paginated list of speech history items with metadata.

get()

Inputs

Name	Type	Required	Description
history_item_id	str	Yes	The ID of the history item to retrieve.
request_options	Optional[RequestOptions]	No	Request-specific configuration.

Output

Name	Type	Description
return	SpeechHistoryItemResponse	Full metadata for the requested history item.

delete()

Inputs

Name	Type	Required	Description
history_item_id	str	Yes	The ID of the history item to delete.
request_options	Optional[RequestOptions]	No	Request-specific configuration.

Output

Name	Type	Description
return	DeleteHistoryItemResponse	Confirmation of the deletion.

get_audio()

Inputs

Name	Type	Required	Description
history_item_id	str	Yes	The ID of the history item whose audio to retrieve.
request_options	Optional[RequestOptions]	No	Request-specific configuration. Supports `chunk_size` (default 1024 bytes).

Output

Name	Type	Description
return	Iterator[bytes]	Streaming iterator of audio byte chunks for the history item.

download()

Inputs

Name	Type	Required	Description
history_item_ids	Sequence[str]	Yes	List of history item IDs to download.
output_format	Optional[str]	No	Output format to transcode the audio file. Can be 'wav' or 'default'.
request_options	Optional[RequestOptions]	No	Request-specific configuration. Supports `chunk_size` (default 1024 bytes).

Output

Name	Type	Description
return	Iterator[bytes]	Streaming iterator of bytes. Returns a single audio file for one item, or a .zip archive for multiple items.

API Endpoints

Method	HTTP Verb	Endpoint
list	GET	`/v1/history`
get	GET	`/v1/history/{history_item_id}`
delete	DELETE	`/v1/history/{history_item_id}`
get_audio	GET	`/v1/history/{history_item_id}/audio`
download	POST	`/v1/history/download`

Error Handling

All methods may raise:

UnprocessableEntityError (HTTP 422) - When the request fails validation. The error body is typed as HttpValidationError.
BadRequestError (HTTP 400) - Raised specifically by the download method for invalid requests. The error body is typed as BadRequestErrorBody.
ApiError - For any other non-2xx HTTP status codes.

Usage Examples

Listing History Items

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
history = client.history.list(
    page_size=10,
    sort_direction="asc",
    source="TTS",
)
for item in history.history:
    print(item.history_item_id, item.text)

Retrieving a Single History Item

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
item = client.history.get(
    history_item_id="VW7YKqPnjY4h39yTbx2L",
)

Downloading Audio for a History Item

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Stream audio to a file
with open("output.mp3", "wb") as f:
    for chunk in client.history.get_audio(history_item_id="history_item_id"):
        f.write(chunk)

Bulk Downloading Multiple History Items

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Downloads as a zip file when multiple IDs are provided
with open("history_items.zip", "wb") as f:
    for chunk in client.history.download(
        history_item_ids=["item_id_1", "item_id_2"],
        output_format="wav",
    ):
        f.write(chunk)

Deleting a History Item

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
client.history.delete(
    history_item_id="VW7YKqPnjY4h39yTbx2L",
)

Async Usage

import asyncio
from elevenlabs import AsyncElevenLabs

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def main() -> None:
    history = await client.history.list(page_size=5)
    item = await client.history.get(
        history_item_id="VW7YKqPnjY4h39yTbx2L",
    )

asyncio.run(main())

Related Pages

Environment:Elevenlabs_Elevenlabs_python_Python_Httpx

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment