Usage reporting endpoints

Request ledger

GET /v1/usage/requests with from, to, route_class, and limit parameters

In the backend source, the response contains data, next_cursor, and admissions_captured_at. Each row describes request ID, key ID, route class, admission/finalization timestamps, state, HTTP status, whether the request was charged, returned-record count, and policy IDs/versions. Several fields can be null.

Analytics

GET /v1/usage/analytics returns daily aggregates. Optional group_by accepts route_class, status_class, or api_key_id; omitted grouping yields one all-group per UTC day. Metrics include request events, charged/pending/rate-limited/usage-limited requests, status counts, error rate, and returned job/company records.

Report bounds

Both routes require from and to UTC RFC 3339 timestamps with from < to and a period no longer than 31 days. Optional route_class and api_key_id are validated. Requests reports also accept limit 1–100, default 50, and an opaque cursor. Repeated or unknown parameters return 400.

Time basis and limits

Request/status metrics group by UTC admission day; returned-record metrics group by UTC finalization day. error_rate is the number of charged requests with a 4xx or 5xx response divided by charged requests, rounded to four decimal places. It is null when there are no charged requests; uncharged rate-limit rejections are excluded from both counts. Analytics can return 422 when source rows exceed 100,000 or groups exceed 1,000. Reports exclude their own request from the rows and settle zero returned records.

A report is not an invoice

Usage rows describe admitted requests and source settlement fields. They do not expose a dollar balance or invoice. Admission consumes request-window allowance, and customer-wide policies may share limits across keys. Exact limits are provisioned per customer; the source does not establish universal values.

Example empty fixture

{"data":[],"next_cursor":null,"admissions_captured_at":"2026-09-22T12:00:00.000Z"}