Skip to main content
GET
Get Agent 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-03-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. Must be strictly after start_ts.

Example:

"2026-03-08T00: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.