Usage

1 endpoint

get/v1/usage

Read aggregated usage for the authenticated API key

Returns the aggregation buckets (hourly or daily) of the authenticated key's usage over a given time range, plus totals computed application-side. Use it to size your usage, monitor latencies, and spot rate limit rejections.

No specific scope is required (same pattern as GitHub's /rate_limit): reading your own metrics is free and always allowed for any authenticated key.

The range (to - from) must be strictly positive and must not exceed 90 days. Returned buckets are sorted by bucket_start ASC; windows with no traffic are omitted from the array (no zero-padding).

Required scopes:

Query parameters

Name	Type	Required	Description
`from`	`string`	required	Lower bound (inclusive) of the time range, ISO 8601 UTC.
`to`	`string`	required	Upper bound (exclusive) of the time range, ISO 8601 UTC. Must be strictly after `from`, and the range `(to - from)` must be ≤ 90 days.
`granularity`	`string`	optional	Granularity of the returned buckets. Defaults to `day`.

Responses

Status	Description
`200`	Usage buckets and totals for the requested range.
`400`	The request is malformed (missing header, invalid JSON, invalid parameter).
`401`	Unknown API key or invalid format.
`429`	The per-window request quota has been exceeded for this API key or endpoint.
`500`	Unexpected server error. Always include the `request_id` when contacting support.

Example request

curl -X GET 'https://api.capturia.io/v1/usage' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'