Skip to main content
GET
Get an agent's usage

Authorizations

Authorization
string
header
required

OAuth 2.0 / OIDC bearer token.

Tenant-Name
string
header
required

The tenant the request operates within.

Path Parameters

agentId
string<agent-id>
required

Agent identifier (prefixed UUIDv7). Agent identifier. Accepts agt.<uuidv7> or a bare UUIDv7 on input; always returned prefixed.

Pattern: ^(agt\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40"

Query Parameters

from
string<date-time>

Inclusive start of the range, as an RFC 3339 timestamp (UTC). Defaults to 30 days before to. Must not be after to.

to
string<date-time>

Exclusive end of the range, as an RFC 3339 timestamp (UTC). Defaults to the current time.

granularity
enum<string>
default:day

Size of each reporting bucket. Defaults to day. The size of each usage reporting bucket. Only day is currently honored; minute, hour, and week are accepted but produce daily buckets (the server always returns day).

Available options:
minute,
hour,
day,
week

Response

The agent's bucketed usage over the requested range.

An agent's bucketed usage over a date range, with range-wide totals.

granularity
enum<string>
default:day
required

The size of each usage reporting bucket. Only day is currently honored; minute, hour, and week are accepted but produce daily buckets (the server always returns day).

Available options:
minute,
hour,
day,
week
from
string<date-time>
required

Resolved inclusive start of the range (UTC).

Example:

"2026-05-19T00:00:00Z"

to
string<date-time>
required

Resolved exclusive end of the range (UTC).

Example:

"2026-05-21T00:00:00Z"

totals
object
required

Aggregate metrics across the whole range.

buckets
object[]
required

One entry per period with activity, ordered oldest first.