Skip to main content
GET
Retrieve advanced API usage analytics
Returns generated-audio minutes aggregated into time buckets, optionally broken down by voice, API key, or model. Use this for dashboards, internal reporting, and per-key attribution. For a simpler per-voice rollup keyed by date, use Get voice usage instead.

Endpoint

Query parameters

Restrictions

  • voice_id and voice_name cannot both appear in breakdown_type in a single request.
  • If start_time and end_time have different UTC offsets, the offset on end_time is ignored — use matching offsets.
  • If breakdown_type is omitted, the response returns the total generated time per bucket (no per-dimension breakdown).

See also

Docs: Cost and usage

Patterns for monitoring spend in production.

Get voice usage

Simpler per-voice rollup by date.

Authorizations

x-sup-api-key
string
header
required

Query Parameters

start_time
string
required

Start time in RFC3339 format

Example:

"2024-01-01T00:00:00+09:00"

end_time
string
required

End time in RFC3339 format

Example:

"2024-01-31T23:59:59+09:00"

bucket_width
enum<string>
default:day

Time bucket width for aggregation

Available options:
hour,
day
breakdown_type
enum<string>[]

Dimensions to break down usage data

Available options:
voice_id,
voice_name,
api_key,
model
Example:
page_size
number
default:10

Number of results per page

Required range: 1 <= x <= 20
next_page_token
string

Pagination token from previous response

Response

Usage analytics data successfully retrieved.

data
object[]
required

Array of time buckets containing usage data

total
number
required

Total number of time buckets across all pages

next_page_token
string

Pagination token for next page