Skip to main content
Get usage summary

Authorizations

Authorization
string
header
required

Live API key minted in the dashboard. Pass as Authorization: Bearer sk_live_…. Keys are scoped to a single environment (staging / prod).

Query Parameters

period
enum<string> | null

Convenience period selector; mutually exclusive with explicit range.

Available options:
current_month,
previous_month
period_start
string<date-time> | null

ISO-8601 UTC. Must be paired with period_end.

period_end
string<date-time> | null

ISO-8601 UTC. Must be paired with period_start.

time_zone
string | null

IANA timezone for daily credit buckets.

Maximum string length: 64

Response

Successful Response

Aggregated usage; returned by GET /v1/usage.

billable_seconds
integer
required

Total billable seconds across all sessions in the window.

Required range: x >= 0
period_end
string<date-time>
required

Exclusive end of the aggregated window. Matches the period_end query argument.

period_start
string<date-time>
required

Inclusive start of the aggregated window. Matches the period_start query argument.

sessions
integer
required

Number of sessions that contributed usage in the window.

Required range: x >= 0
by_billing_surface
object

credits_charged per billing surface.

by_embed
EmbedUsageSummary · object[]

Embed-attributed usage, ordered by credits then time.

by_model
object

credits_charged per model identifier, across every charge in the window. Charges that are not attributed to a model are omitted, as are charges for internal models that are not offered as customer-facing models, so these values intentionally do not sum to credits_charged. Unlike recent_charges, this covers the whole window rather than the most recent settled charges.

by_operation
object

credits_charged per durable billable operation identifier.

by_quality
object

billable_seconds per quality tier. Forward-compatible breakdown — additional by_* slices may appear over time.

by_speech_billing_mode
object

credits_charged per speech billing mode.

credits_charged
integer
default:0

Total credits charged across all usage events in the window.

Required range: x >= 0
daily_credits_by_billing_surface
object

credits_charged per requested timezone day and billing surface. Keys use YYYY-MM-DD.

recent_charges
UsageChargeSummary · object[]

Most recent settled model and Studio charges in the requested window.