Usage

Track character usage and billing statistics

Overview

The usage client provides methods to retrieve detailed usage statistics for your ElevenLabs account, including character consumption breakdown by feature.

get_character_usage()

Get character usage statistics for a specified time period.

Method Signature

client.usage.get_character_usage(
    start_unix: Optional[int] = None,
    end_unix: Optional[int] = None,
    request_options: Optional[RequestOptions] = None
) -> CharacterUsageResponse

Parameters

start_unix · int

Start of the time period as a Unix timestamp. Defaults to the beginning of the current billing period.

end_unix · int

End of the time period as a Unix timestamp. Defaults to the current time.

request_options · RequestOptions

Request-specific configuration.

Returns

CharacterUsageResponse containing:

character_count · int

Total characters used in the specified period

breakdown · object

Character usage broken down by feature

Show breakdown properties

text_to_speech · int

Characters used for text-to-speech generation

speech_to_speech · int

Characters used for speech-to-speech conversion

voice_cloning · int

Characters used for voice cloning operations

projects · int

Characters used in projects (e.g., dubbing, audio native)

Example

from elevenlabs import ElevenLabs
import time

client = ElevenLabs(api_key="YOUR_API_KEY")

# Get usage for the last 30 days
end_time = int(time.time())
start_time = end_time - (30 * 24 * 60 * 60)  # 30 days ago

usage = client.usage.get_character_usage(
    start_unix=start_time,
    end_unix=end_time
)

print(f"Total characters used: {usage.character_count}")
print(f"\nBreakdown:")
print(f"  Text-to-speech: {usage.breakdown.text_to_speech}")
print(f"  Speech-to-speech: {usage.breakdown.speech_to_speech}")
print(f"  Voice cloning: {usage.breakdown.voice_cloning}")
print(f"  Projects: {usage.breakdown.projects}")

Example Output

Total characters used: 45823

Breakdown:
  Text-to-speech: 32150
  Speech-to-speech: 8420
  Voice cloning: 3253
  Projects: 2000

get_usage_by_date()

Get usage statistics grouped by date.

from datetime import datetime, timedelta

# Get daily usage for the last week
end_date = datetime.now()
start_date = end_date - timedelta(days=7)

daily_usage = client.usage.get_usage_by_date(
    start_unix=int(start_date.timestamp()),
    end_unix=int(end_date.timestamp())
)

for day in daily_usage.usage:
    print(f"{day.date}: {day.character_count} characters")

Async Usage

from elevenlabs import AsyncElevenLabs
import asyncio
import time

async def get_usage_stats():
    client = AsyncElevenLabs(api_key="YOUR_API_KEY")
    
    end_time = int(time.time())
    start_time = end_time - (7 * 24 * 60 * 60)  # Last 7 days
    
    usage = await client.usage.get_character_usage(
        start_unix=start_time,
        end_unix=end_time
    )
    
    print(f"Characters used (last 7 days): {usage.character_count}")
    return usage

usage = asyncio.run(get_usage_stats())

Monitoring Usage

Create a simple usage monitoring script:

from elevenlabs import ElevenLabs
import time

def check_usage_percentage(client):
    """Check what percentage of quota has been used."""
    # Get user info for limits
    user = client.user.get()
    character_limit = user.subscription.character_limit
    
    # Get current period usage
    usage = client.usage.get_character_usage()
    used = usage.character_count
    
    percentage = (used / character_limit) * 100
    
    print(f"Usage: {used:,} / {character_limit:,} characters ({percentage:.1f}%)")
    
    if percentage > 90:
        print("⚠️ Warning: Usage exceeds 90% of quota")
    elif percentage > 75:
        print("⚠️ Caution: Usage exceeds 75% of quota")
    else:
        print("✓ Usage is within normal range")
    
    return percentage

client = ElevenLabs(api_key="YOUR_API_KEY")
check_usage_percentage(client)

Use Cases

Quota Monitoring

Track usage against your subscription limits

Cost Tracking

Monitor character consumption for budgeting

Usage Analytics

Analyze which features consume the most characters

Alerts

Set up automated alerts when approaching limits

Related Methods

• User - Get account and subscription information
• Models - Available AI models