Skip to main content
GET
/
usage
/
agents
Get Agent Usage
curl --request GET \
  --url https://api.cartesia.ai/usage/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Cartesia-Version: <cartesia-version>'
{
  "data": [
    {
      "start_ts": "2026-01-01T00:00:00.000Z",
      "end_ts": "2026-01-02T00:00:00.000Z",
      "cents": 123,
      "minutes": 123,
      "calls": 123
    }
  ]
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
Cartesia-Version
enum<string>
required

API version header.

Available options:
2024-06-10,
2024-11-13,
2025-04-16,
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). Defaults to a few days before end_ts. Rounded down to the start of the UTC day. start_ts to end_ts cannot span more than a year.

Example:

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

​
end_ts
string<date-time> | null

End of the time window, as an RFC 3339 datetime (with timezone). Defaults to now. 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-03-01T00:00:00Z"

​
interval
enum<string> | null

Omit to receive a single bucket spanning from start_ts to end_ts. Groups usage data into buckets according to time.

Available options:
day,
week,
month

Response

200 - application/json
​
data
UsageAgentsBucket · object[]
required

Agent usage buckets in chronological order. Buckets with no recorded activity are returned with zero values.