---
title: "API usage aggregations"
method: GET
path: "/api/v1/usage"
tags: ["Discovery"]
---

# API usage aggregations

`GET /api/v1/usage`

## Request

- Base URL: `https://legal.nexusquantum.legal`
- URL: `https://legal.nexusquantum.legal/api/v1/usage`
- Auth: HTTP bearer

Returns aggregated API usage metrics for the authenticated account. Required by partners that bill their own clients on individual per-sub-key consumption.

Filters: `from`/`to` (ISO date), `granularity` (day/week/month), `api_key_id`, `endpoint`. Format: JSON (default) or CSV with `?format=csv`.

## Query parameters

- `from` string, date
- `to` string, date
- `granularity` 'day' | 'week' | 'month'
- `api_key_id` string, uuid
- `endpoint` string
- `format` 'json' | 'csv'

## Response `200`

Usage aggregations.

- object
  - `period` object
    - `from` string, date
    - `to` string, date
    - `granularity` 'day' | 'week' | 'month'
  - `totals` object
    - `calls` integer
    - `errors` integer
    - `latency_p50_ms` integer
    - `latency_p95_ms` integer
    - `credits_consumed` number: Credits consumed (Σ of the `consumption` ledger) in the range, over the key set resolved by ownership. Additive (v1.30.0).
    - `rate_limited` integer: Number of 429 (rate-limited) responses in the range. Additive (v1.31.0).
  - `by_key` object[]: Breakdown by sub-key.
    - `api_key_id` string, uuid, nullable
    - `key_prefix` string, nullable
    - `calls` integer
    - `errors` integer
    - `credits_consumed` number: Credits consumed by this key in the range. Additive (v1.30.0).
    - `byo_calls` integer: Requests served by a BYO engine (routing_policy own_*). Additive (v1.30.0).
    - `platform_calls` integer: Requests served by the platform chain. Additive (v1.30.0).
    - `rate_limited` integer: Number of 429 (rate-limited) responses attributed to this key. Additive (v1.31.0).
  - `by_endpoint` object[]
  - `buckets` object[]

---

[API](https://skmtc.dev/nexusquantum/apis/nexus-legal-api.md) · [All operations](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/revisions/4084d8d4eb0b?raw)