Tokens

Get API Key usage

Authentication: API key — any valid key is accepted and the response only ever covers the calling key. The key id is taken from the authenticated credential, never from the request, so one key cannot read another's usage. Counters are hourly rollups written by the API's background flusher, so the most recent bucket lags real time by up to one flush interval. Optional query filters: from, to, granularity (hour|day|total), group_by (scope|route).

get /tokens/usage

Authorizations

x-api-key string header required

Talus API Key in the form key_id.secret. The API also accepts Authorization: ApiKey <key_id.secret>, but the docs UI is configured to send x-api-key.

Query Parameters

from string | null

Inclusive lower bound as an RFC 3339 timestamp. Defaults to 7 days ago.

to string | null

Exclusive upper bound as an RFC 3339 timestamp. Defaults to now.

granularity string | null

Bucket width: hour (default), day, or total.

group_by string | null

Grouping dimension: scope (default) or route.

200application/json

Usage rollups for the calling API key

buckets object[] required
avg_duration_ms integer<int64> required

Mean server-side duration over the bucket, in milliseconds.

bucket_start string | null

Start of the bucket, RFC 3339. null when granularity=total.

group string required

The grouping value: an API-key scope, or a matched route template.

request_count integer<int64> required
status_class string required
from string required
granularity string required
group_by string required
key_id string required
to string required
total_requests integer<int64> required

Total requests across every returned bucket.

400

Invalid filter value

401

API key missing or invalid

500

Internal server error