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
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
