Skip to main content
GET
Get Credit Usage

Authorizations

Authorization
string
header
default:$CARTESIA_ADMIN_API_KEY
required

Cartesia admin API key (sk_car_admin_...). Get one at play.cartesia.ai/keys/admin.

Headers

Cartesia-Version
enum<string>
default:2026-03-01
required

API version header.

Available options:
2026-03-01
Example:

"2026-03-01"

Query Parameters

start_ts
string<date-time> | null

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.

Example:

"2026-01-01T00:00:00Z"

end_ts
string<date-time> | null

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.

Example:

"2026-01-03T00:00:00Z"

interval
enum<string> | null

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.

Available options:
day,
week,
month
api_key_id
string<uuid> | null

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.

group_by
enum<string> | null

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.

Available options:
capability,
model,
voice,
api_key

Response

200 - application/json
data
(UsageCreditsBucket · object | UsageCreditsBreakdownSeries · object)[]
required

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.

group_by
enum<string>

Present when the request included group_by.

Available options:
capability,
model,
voice,
api_key