---
title: "Get Credit Usage"
method: GET
path: "/usage/credits"
tags: ["Usage"]
---

# Get Credit Usage

`GET /usage/credits`

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

## Query parameters

- `start_ts` string, date-time, nullable
- `end_ts` string, date-time, nullable
- `interval` 'day' | 'week' | 'month' — Groups usage data into buckets according to time.
- `api_key_id` string, uuid, nullable
- `group_by` 'capability' | 'model' | 'voice' | 'api_key' — Dimension to break credit usage down by.

## Headers

- `Cartesia-Version` '2026-03-01', date, required

## Response `200`

- UsageCreditsResponse
  - `group_by` 'capability' | 'model' | 'voice' | 'api_key' — Dimension to break credit usage down by.
  - `data` union[], 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`.
    - union
      - UsageCreditsBucket — A single bucket of credit usage within a time window.
        - `start_ts` string, date-time, required — RFC 3339 timestamp for the start of the usage bucket.
        - `end_ts` string, date-time, required — RFC 3339 timestamp for the end of the usage bucket.
        - `credits` integer, required — Total credits consumed within the bucket.
      - UsageCreditsBreakdownSeries — Credit usage for one value of the requested group-by dimension.
        - `id` string, required — Identifier for the dimension value (capability id, model id, voice id, or API key id / sentinel such as `playground` or `unnamed_key`).
        - `label` string, nullable — Human-readable label when available (voice name, API key description, etc.).
        - `buckets` UsageCreditsBucket[], required — Daily credit buckets for this dimension value.
          - `start_ts` string, date-time, required — RFC 3339 timestamp for the start of the usage bucket.
          - `end_ts` string, date-time, required — RFC 3339 timestamp for the end of the usage bucket.
          - `credits` integer, required — Total credits consumed within the bucket.

---

[API](https://skmtc.net/cartesia/apis/cartesia-api.md) · [All operations](https://skmtc.net/cartesia/apis/cartesia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cartesia/cartesia-api/revisions/8910812440d3/schema)