Track API usage with time-based aggregation and breakdown by resource type. Monitor character consumption, request counts, and usage patterns across different services.

Quick Reference

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });
// Access this API via: client.usage

Capabilities

Get Usage Statistics

Retrieve usage metrics for a specific time period with optional aggregation and breakdown.

/**
 * @param request - Time period and aggregation options
 * @param requestOptions - Optional request configuration
 * @returns Usage statistics
 * @throws UnprocessableEntityError if request fails
 */
client.usage.get(
  request: UsageGetRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<UsageCharactersResponseModel>;

interface UsageGetRequest {
  /** Start time (Unix timestamp in seconds) */
  startUnix: number;
  /** End time (Unix timestamp in seconds) */
  endUnix: number;
  /** Include workspace-wide metrics */
  includeWorkspaceMetrics?: boolean;
  /** Breakdown type (e.g., "voice", "model", "source") */
  breakdownType?: "voice" | "model" | "source" | "product";
  /** Aggregation interval */
  aggregationInterval?: "day" | "month";
  /** Aggregation bucket size */
  aggregationBucketSize?: number;
  /** Metric type to track */
  metric?: "character_count" | "request_count";
}

interface UsageCharactersResponseModel {
  /** Usage summary */
  usage: UsageSummary;
  /** Aggregated usage over time */
  aggregated_usage?: AggregatedUsage[];
  /** Usage breakdown by type */
  breakdown?: UsageBreakdown[];
}

interface UsageSummary {
  /** Total characters used */
  character_count: number;
  /** Total requests made */
  request_count: number;
}

interface AggregatedUsage {
  /** Time bucket (Unix timestamp) */
  timestamp: number;
  /** Characters used in this bucket */
  character_count: number;
  /** Requests made in this bucket */
  request_count: number;
}

interface UsageBreakdown {
  /** Breakdown key (voice_id, model_id, etc.) */
  key: string;
  /** Breakdown key name */
  name: string;
  /** Character count for this key */
  character_count: number;
  /** Request count for this key */
  request_count: number;
}

Usage Examples

Basic Usage Query

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

// Get usage for last 30 days
const endTime = Math.floor(Date.now() / 1000);
const startTime = endTime - (30 * 24 * 60 * 60); // 30 days ago

const usage = await client.usage.get({
  startUnix: startTime,
  endUnix: endTime,
});

console.log("Total Characters:", usage.usage.character_count);
console.log("Total Requests:", usage.usage.request_count);

Daily Aggregation

// Get usage aggregated by day
const usage = await client.usage.get({
  startUnix: startTime,
  endUnix: endTime,
  aggregationInterval: "day",
});

console.log("Daily Usage:");
if (usage.aggregated_usage) {
  for (const day of usage.aggregated_usage) {
    const date = new Date(day.timestamp * 1000);
    console.log(`${date.toLocaleDateString()}:`);
    console.log(`  Characters: ${day.character_count}`);
    console.log(`  Requests: ${day.request_count}`);
  }
}

Usage by Voice

// Break down usage by voice
const usage = await client.usage.get({
  startUnix: startTime,
  endUnix: endTime,
  breakdownType: "voice",
});

console.log("Usage by Voice:");
if (usage.breakdown) {
  for (const voice of usage.breakdown) {
    console.log(`${voice.name}:`);
    console.log(`  Characters: ${voice.character_count}`);
    console.log(`  Requests: ${voice.request_count}`);
  }
}

Usage by Model

// Break down usage by model
const usage = await client.usage.get({
  startUnix: startTime,
  endUnix: endTime,
  breakdownType: "model",
});

console.log("Usage by Model:");
if (usage.breakdown) {
  for (const model of usage.breakdown) {
    console.log(`${model.name}:`);
    console.log(`  Characters: ${model.character_count.toLocaleString()}`);
    console.log(`  Requests: ${model.request_count.toLocaleString()}`);
  }
}

Monthly Report

// Generate monthly usage report
async function generateMonthlyReport(
  year: number,
  month: number
): Promise<void> {
  // Month is 0-indexed (0 = January)
  const startDate = new Date(year, month, 1);
  const endDate = new Date(year, month + 1, 0); // Last day of month

  const usage = await client.usage.get({
    startUnix: Math.floor(startDate.getTime() / 1000),
    endUnix: Math.floor(endDate.getTime() / 1000),
    aggregationInterval: "day",
    breakdownType: "voice",
  });

  console.log(`=== Usage Report: ${startDate.toLocaleDateString("en-US", { month: "long", year: "numeric" })} ===\n`);

  console.log("Total Usage:");
  console.log(`  Characters: ${usage.usage.character_count.toLocaleString()}`);
  console.log(`  Requests: ${usage.usage.request_count.toLocaleString()}\n`);

  if (usage.aggregated_usage) {
    console.log("Daily Breakdown:");
    const avgChars = usage.usage.character_count / usage.aggregated_usage.length;
    const avgReqs = usage.usage.request_count / usage.aggregated_usage.length;
    console.log(`  Average per day: ${Math.round(avgChars).toLocaleString()} characters`);
    console.log(`  Average requests: ${Math.round(avgReqs).toLocaleString()}\n`);
  }

  if (usage.breakdown) {
    console.log("Top Voices:");
    const sortedVoices = usage.breakdown
      .sort((a, b) => b.character_count - a.character_count)
      .slice(0, 5);

    for (let i = 0; i < sortedVoices.length; i++) {
      const voice = sortedVoices[i];
      console.log(`  ${i + 1}. ${voice.name}: ${voice.character_count.toLocaleString()} chars`);
    }
  }
}

await generateMonthlyReport(2024, 0); // January 2024

Workspace Usage

// Get workspace-wide usage metrics
const usage = await client.usage.get({
  startUnix: startTime,
  endUnix: endTime,
  includeWorkspaceMetrics: true,
});

console.log("Workspace Usage:");
console.log(`  Total Characters: ${usage.usage.character_count}`);
console.log(`  Total Requests: ${usage.usage.request_count}`);

Usage by Product

// Break down usage by product (TTS, dubbing, etc.)
const usage = await client.usage.get({
  startUnix: startTime,
  endUnix: endTime,
  breakdownType: "product",
});

console.log("Usage by Product:");
if (usage.breakdown) {
  for (const product of usage.breakdown) {
    console.log(`${product.name}:`);
    console.log(`  Characters: ${product.character_count.toLocaleString()}`);
    console.log(`  Requests: ${product.request_count.toLocaleString()}`);
  }
}

Track Request Counts

// Track only request counts
const usage = await client.usage.get({
  startUnix: startTime,
  endUnix: endTime,
  metric: "request_count",
  aggregationInterval: "day",
});

console.log("Daily Request Count:");
if (usage.aggregated_usage) {
  for (const day of usage.aggregated_usage) {
    const date = new Date(day.timestamp * 1000);
    console.log(`${date.toLocaleDateString()}: ${day.request_count} requests`);
  }
}

Weekly Summary

// Get usage for current week
function getWeekBounds(): { start: number; end: number } {
  const now = new Date();
  const dayOfWeek = now.getDay();
  const startOfWeek = new Date(now);
  startOfWeek.setDate(now.getDate() - dayOfWeek);
  startOfWeek.setHours(0, 0, 0, 0);

  return {
    start: Math.floor(startOfWeek.getTime() / 1000),
    end: Math.floor(Date.now() / 1000),
  };
}

const { start, end } = getWeekBounds();
const usage = await client.usage.get({
  startUnix: start,
  endUnix: end,
  aggregationInterval: "day",
});

console.log("This Week's Usage:");
console.log(`Characters: ${usage.usage.character_count.toLocaleString()}`);
console.log(`Requests: ${usage.usage.request_count.toLocaleString()}`);

Compare Time Periods

// Compare usage between two time periods
async function compareUsage(
  period1Start: number,
  period1End: number,
  period2Start: number,
  period2End: number
): Promise<void> {
  const usage1 = await client.usage.get({
    startUnix: period1Start,
    endUnix: period1End,
  });

  const usage2 = await client.usage.get({
    startUnix: period2Start,
    endUnix: period2End,
  });

  const charDiff = usage2.usage.character_count - usage1.usage.character_count;
  const reqDiff = usage2.usage.request_count - usage1.usage.request_count;
  const charPercent = (charDiff / usage1.usage.character_count) * 100;
  const reqPercent = (reqDiff / usage1.usage.request_count) * 100;

  console.log("Usage Comparison:");
  console.log(`Period 1: ${usage1.usage.character_count} chars, ${usage1.usage.request_count} reqs`);
  console.log(`Period 2: ${usage2.usage.character_count} chars, ${usage2.usage.request_count} reqs`);
  console.log(`Change: ${charDiff > 0 ? "+" : ""}${charPercent.toFixed(1)}% characters, ${reqDiff > 0 ? "+" : ""}${reqPercent.toFixed(1)}% requests`);
}

Usage Visualization Data

// Prepare usage data for charting
async function getUsageForChart(days: number) {
  const endTime = Math.floor(Date.now() / 1000);
  const startTime = endTime - (days * 24 * 60 * 60);

  const usage = await client.usage.get({
    startUnix: startTime,
    endUnix: endTime,
    aggregationInterval: "day",
  });

  if (!usage.aggregated_usage) return [];

  return usage.aggregated_usage.map(day => ({
    date: new Date(day.timestamp * 1000).toLocaleDateString(),
    characters: day.character_count,
    requests: day.request_count,
  }));
}

const chartData = await getUsageForChart(30);
console.log(JSON.stringify(chartData, null, 2));

Peak Usage Detection

// Find peak usage days
async function findPeakUsageDays(days: number): Promise<void> {
  const endTime = Math.floor(Date.now() / 1000);
  const startTime = endTime - (days * 24 * 60 * 60);

  const usage = await client.usage.get({
    startUnix: startTime,
    endUnix: endTime,
    aggregationInterval: "day",
  });

  if (!usage.aggregated_usage) return;

  const sorted = [...usage.aggregated_usage].sort(
    (a, b) => b.character_count - a.character_count
  );

  console.log("Top 5 Peak Usage Days:");
  for (let i = 0; i < Math.min(5, sorted.length); i++) {
    const day = sorted[i];
    const date = new Date(day.timestamp * 1000);
    console.log(`${i + 1}. ${date.toLocaleDateString()}: ${day.character_count.toLocaleString()} characters`);
  }
}

await findPeakUsageDays(30);

Export Usage Data

// Export usage data to CSV
async function exportUsageToCSV(
  startUnix: number,
  endUnix: number,
  filename: string
): Promise<void> {
  const usage = await client.usage.get({
    startUnix,
    endUnix,
    aggregationInterval: "day",
    breakdownType: "voice",
  });

  let csv = "Date,Characters,Requests\n";

  if (usage.aggregated_usage) {
    for (const day of usage.aggregated_usage) {
      const date = new Date(day.timestamp * 1000).toISOString().split("T")[0];
      csv += `${date},${day.character_count},${day.request_count}\n`;
    }
  }

  await writeFile(filename, csv);
  console.log(`Exported to ${filename}`);
}

import { writeFile } from "fs/promises";
await exportUsageToCSV(startTime, endTime, "usage_export.csv");

Version

Tile

Files

usage.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/management/

Usage Analytics