Get Credit Usage
Returns your credit usage over time, bucketed by the requested interval.
Authorizations
Cartesia admin API key (sk_car_admin_...). Get one at play.cartesia.ai/keys/admin.
Headers
API version header.
2026-03-01 "2026-03-01"
Query Parameters
Start of the time window, as an RFC 3339 datetime (with timezone). Rounded down to the start of the UTC day. start_ts to end_ts cannot span more than a year.
"2026-01-01T00:00:00Z"
End of the time window, as an RFC 3339 datetime (with timezone). Rounded up to the start of the next UTC day, unless already at midnight. start_ts to end_ts cannot span more than a year.
"2026-01-03T00:00:00Z"
Omit to receive a single bucket spanning from start_ts to end_ts. When group_by is set, must be day if provided.
Groups usage data into buckets according to time.
day, week, month Filter usage to a single API key. When set, only credits attributable to that key are returned. Can be combined with group_by for other dimensions (capability, model, voice), but not with group_by=api_key.
Break down credit usage by capability, model, voice, or API key. When interval is set it must be day. Cannot be combined with api_key_id when group_by=api_key.
Dimension to break credit usage down by.
capability, model, voice, api_key Response
Without group_by, flat credit usage buckets in chronological order. With group_by, one entry per dimension value; each item includes id, optional label, and nested daily buckets. Empty usage periods are returned with credits: 0.
A single bucket of credit usage within a time window.
- UsageCreditsBucket
- UsageCreditsBreakdownSeries
Present when the request included group_by.
capability, model, voice, api_key