---
title: "GET /v1/usage"
method: GET
path: "/v1/usage"
---

# GET /v1/usage

`GET /v1/usage`

Retrieve aggregate spend, request, and token usage for the authenticated API key, grouped by UTC day, model, or both.

## Query parameters

- `from` string, date
- `to` string, date
- `group_by` 'day' | 'model' | 'day,model' | 'model,day'
- `scope` 'current_key' | 'api_key'
- `api_key_id` integer

## Response `200`

Aggregate usage for the authenticated API key

- UsageResponse
  - `object` 'usage', required — Always usage.
  - `scope` 'current_key' | 'api_key', required — Echoes the requested usage scope.
  - `apiKey` object, required
    - `id` integer, required — Numeric ID of the authenticated API key.
  - `from` string, date, required — UTC start date.
  - `to` string, date, required — UTC end date, inclusive.
  - `timezone` 'UTC', required — Always UTC.
  - `groupBy` 'day' | 'model' | 'day,model', required — The effective grouping mode.
  - `asOf` string, date-time, required — Timestamp when the aggregate response was generated. Cached responses can be up to 60 seconds old.
  - `source` UsageSource, required
    - `rollupDays` string[], required — Days served from precomputed daily rollups.
    - `liveDays` string[], required — Days served from live aggregation, usually today or days not rolled up yet.
    - `missingRollupDays` string[], required — Closed UTC days that were not available in the rollup table and had to be served live.
  - `totals` UsageCounterBucket, required
    - `date` string, date — UTC date for day-grouped buckets.
    - `model` string — Public model label for model-grouped buckets.
    - `requests` integer, required — Number of billable usage requests in the aggregate bucket.
    - `costUsd` number, required — Gross USD usage cost before refunds.
    - `refundedUsd` number, required — USD amount refunded in the aggregate bucket.
    - `netCostUsd` number, required — max(0, costUsd - refundedUsd) for the aggregate bucket.
    - `inputTokens` integer, required — Input tokens counted for the bucket.
    - `outputTokens` integer, required — Output tokens counted for the bucket.
    - `reasoningTokens` integer, required — Reasoning tokens counted separately when available.
    - `totalTokens` integer, required — inputTokens + outputTokens. Reasoning tokens are reported separately and are not added to totalTokens.
  - `byDay` UsageCounterBucket[] — Returned when grouped by day.
    - `date` string, date — UTC date for day-grouped buckets.
    - `model` string — Public model label for model-grouped buckets.
    - `requests` integer, required — Number of billable usage requests in the aggregate bucket.
    - `costUsd` number, required — Gross USD usage cost before refunds.
    - `refundedUsd` number, required — USD amount refunded in the aggregate bucket.
    - `netCostUsd` number, required — max(0, costUsd - refundedUsd) for the aggregate bucket.
    - `inputTokens` integer, required — Input tokens counted for the bucket.
    - `outputTokens` integer, required — Output tokens counted for the bucket.
    - `reasoningTokens` integer, required — Reasoning tokens counted separately when available.
    - `totalTokens` integer, required — inputTokens + outputTokens. Reasoning tokens are reported separately and are not added to totalTokens.
  - `byModel` UsageCounterBucket[] — Returned when grouped by model.
    - `date` string, date — UTC date for day-grouped buckets.
    - `model` string — Public model label for model-grouped buckets.
    - `requests` integer, required — Number of billable usage requests in the aggregate bucket.
    - `costUsd` number, required — Gross USD usage cost before refunds.
    - `refundedUsd` number, required — USD amount refunded in the aggregate bucket.
    - `netCostUsd` number, required — max(0, costUsd - refundedUsd) for the aggregate bucket.
    - `inputTokens` integer, required — Input tokens counted for the bucket.
    - `outputTokens` integer, required — Output tokens counted for the bucket.
    - `reasoningTokens` integer, required — Reasoning tokens counted separately when available.
    - `totalTokens` integer, required — inputTokens + outputTokens. Reasoning tokens are reported separately and are not added to totalTokens.
  - `byDayModel` UsageCounterBucket[] — Returned when grouped by both day and model.
    - `date` string, date — UTC date for day-grouped buckets.
    - `model` string — Public model label for model-grouped buckets.
    - `requests` integer, required — Number of billable usage requests in the aggregate bucket.
    - `costUsd` number, required — Gross USD usage cost before refunds.
    - `refundedUsd` number, required — USD amount refunded in the aggregate bucket.
    - `netCostUsd` number, required — max(0, costUsd - refundedUsd) for the aggregate bucket.
    - `inputTokens` integer, required — Input tokens counted for the bucket.
    - `outputTokens` integer, required — Output tokens counted for the bucket.
    - `reasoningTokens` integer, required — Reasoning tokens counted separately when available.
    - `totalTokens` integer, required — inputTokens + outputTokens. Reasoning tokens are reported separately and are not added to totalTokens.

## Other responses

- `400` — Invalid date range, unsupported parameter, invalid grouping, or request for a different API key
- `401` — Missing or invalid API key
- `429` — Too many usage requests
- `500` — Unexpected usage retrieval failure
- `503` — Usage API temporarily unavailable or requested rollup data is not ready yet

---

[API](https://skmtc.dev/nano-gpt/apis/nanogpt-api.md) · [All operations](https://skmtc.dev/nano-gpt/apis/nanogpt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nano-gpt/nanogpt-api/revisions/584e96d146b0/schema)