Skip to main content
GET
/
v1
/
voice-usage
Retrieve TTS API usage data
curl --request GET \
  --url https://supertoneapi.com/v1/voice-usage \
  --header 'x-sup-api-key: <api-key>'
{
  "usages": [
    {
      "date": "<string>",
      "voice_id": "<string>",
      "total_minutes_used": 123,
      "name": "<string>",
      "style": "<string>",
      "language": "<string>",
      "model": "<string>",
      "thumbnail_url": "<string>"
    }
  ]
}
Returns generated-audio minutes for each (date, voice, style, language, model) combination over the requested period. Both preset voices and custom voices appear in the response. For bucketed analytics with custom breakdowns (e.g. by api_key), use Get usage instead.
Dates are UTC+0. Maximum query window is 30 days.

​
Endpoint

GET https://supertoneapi.com/v1/voice-usage

​
Query parameters

NameRequiredDescription
start_date✅Start date in YYYY-MM-DD, UTC+0.
end_date✅End date in YYYY-MM-DD, UTC+0.

​
Request example

GET /v1/voice-usage?start_date=2025-05-19&end_date=2025-05-28
x-sup-api-key: $SUPERTONE_API_KEY

​
Response example

{
  "usages": [
    {
      "date": "2025-05-22",
      "voice_id": "e5f6fb1a53d0add87afb4f",
      "name": "Agatha",
      "style": "neutral",
      "language": "en",
      "model": "sona_speech_1",
      "total_minutes_used": 12.43251349
    },
    {
      "date": "2025-05-24",
      "voice_id": "opSGuRvHBe7EfZ4LQga1hE",
      "name": "My Voice 1",
      "style": "sad",
      "language": "ko",
      "model": "sona_speech_1",
      "total_minutes_used": 3.24566213
    }
  ]
}

​
Notes

  • If no usage was recorded in the window, usages is an empty array.
  • total_minutes_used reflects the actual length of generated audio (the same length used for credit deduction).
  • Useful for monthly budget reports and identifying which characters drive the most cost.

​
See also

Docs: Cost and usage

Operational patterns: weekly reports, anomaly alerts, attribution.

Get usage

Bucketed analytics with multi-dimensional breakdowns.

Authorizations

​
x-sup-api-key
string
header
required

Query Parameters

​
start_date
string
required

The start date in YYYY-MM-DD format.

Example:

"2024-11-01"

​
end_date
string
required

The end date in YYYY-MM-DD format.

Example:

"2024-11-30"

Response

A list of TTS API usage records matching the specified date range.

​
usages
object[]
required