Sign in

v1

latestOpenAPI 3.0.12026-07-2696152184.1 KB
Usage

Get Credit Usage

Returns your credit usage over time, bucketed by the requested interval.

get/usage/credits

Query parameters

start_tsstring date-time nullable
Example:2026-01-01T00:00:00Z

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.

end_tsstring date-time nullable
Example:2026-01-03T00: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.

interval'day' | 'week' | 'month'

Groups usage data into buckets according to time.

Omit to receive a single bucket spanning from start_ts to end_ts. When group_by is set, must be day if provided.

api_key_idstring uuid nullable

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'capability' | 'model' | 'voice' | 'api_key'

Dimension to break credit usage down by.

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.

Headers

Cartesia-Version'2026-03-01' date required
Example:2026-03-01

API version header.

Response

group_by'capability' | 'model' | 'voice' | 'api_key'

Dimension to break credit usage down by.

Example response

{
  "data": [
    {
      "start_ts": "2026-01-01T00:00:00.000Z",
      "end_ts": "2026-01-02T00:00:00.000Z"
    }
  ]
}