---
title: "Usage Summary"
method: GET
path: "/v1/usage/summary"
tags: ["usage"]
---

# Usage Summary

`GET /v1/usage/summary`

Aggregate spend, tokens, and request volume for the dashboard Usage page.

Range-bounded (default last 30 days, hard-capped): unlike the raw ``/v1/usage``
list, every aggregate is scoped to a bounded window so it stays served by the
timestamp index. Returns grand totals, breakdowns by model / user / API key /
source / session (``source_label``) / endpoint / provider (top rows plus a
reconciling ``other`` fold), and a UTC-bucketed time series.

Each breakdown is its own ``GROUP BY`` pass, so a caller that reads only the
totals or the series should narrow ``dimensions`` rather than pay for all seven
(the dashboard's tiles, timeline context, and model typeahead all do). Omitting
the parameter keeps the full set.

## Query parameters

- `start_date` string, date-time, nullable — Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)
- `end_date` string, date-time, nullable — Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)
- `user_id` string, nullable — Filter to a single user
- `status` string, nullable — Filter to a single status (e.g. 'success' or 'error')
- `model` string, nullable — Filter to a single model
- `endpoint` string, nullable — Filter to a single endpoint (e.g. '/v1/chat/completions')
- `provider` string, nullable — Filter to a single provider (e.g. 'openai')
- `source` string, nullable — Filter to a single provenance source (e.g. 'gateway' or 'claude_code')
- `source_label` string, nullable — Filter to a single session/project label (the source_label carried by imported usage)
- `api_key_id` string, nullable — Filter to a single API key id
- `priced` boolean, nullable — Filter by pricing state: true = only rows with a cost, false = only unpriced rows (cost is null)
- `counts_toward_budget` boolean, nullable — Filter by budget participation: true = only enforced gateway rows, false = only imported rows that never touch a budget
- `bucket` 'hour' | 'day' — Time-series granularity: 'hour' or 'day'
- `dimensions` string[], nullable — Which breakdowns to compute; repeatable (dimensions=model&dimensions=user). Each value names the 'by_<value>' response field it fills. Omit for every breakdown (the default); pass 'none' for a totals-and-series-only response. Each dimension left out skips one GROUP BY scan, so a caller that reads only the tiles or the time series should say so. Fields that were not requested come back empty.

## Response `200`

Successful Response

- UsageSummary — Aggregate spend/volume for the Usage & analytics page. Every breakdown field is always present. One the caller excluded through ``dimensions`` comes back as an empty list, the same shape a window with no matching rows produces, so narrowing the selector never changes the schema.
  - `bucket` 'hour' | 'day', required
  - `by_api_key` UsageGroupRow[], required
    - `cost` number, required
    - `is_other` boolean
    - `key` string, nullable, required
    - `requests` integer, required
    - `tokens` integer, required
  - `by_endpoint` UsageGroupRow[], required
    - `cost` number, required
    - `is_other` boolean
    - `key` string, nullable, required
    - `requests` integer, required
    - `tokens` integer, required
  - `by_model` UsageGroupRow[], required
    - `cost` number, required
    - `is_other` boolean
    - `key` string, nullable, required
    - `requests` integer, required
    - `tokens` integer, required
  - `by_provider` UsageGroupRow[], required
    - `cost` number, required
    - `is_other` boolean
    - `key` string, nullable, required
    - `requests` integer, required
    - `tokens` integer, required
  - `by_source` UsageGroupRow[], required
    - `cost` number, required
    - `is_other` boolean
    - `key` string, nullable, required
    - `requests` integer, required
    - `tokens` integer, required
  - `by_source_label` UsageGroupRow[], required
    - `cost` number, required
    - `is_other` boolean
    - `key` string, nullable, required
    - `requests` integer, required
    - `tokens` integer, required
  - `by_user` UsageGroupRow[], required
    - `cost` number, required
    - `is_other` boolean
    - `key` string, nullable, required
    - `requests` integer, required
    - `tokens` integer, required
  - `end_date` string, required
  - `series` UsageSeriesPoint[], required
    - `bucket_start` string, required
    - `cost` number, required
    - `requests` integer, required
    - `tokens` integer, required
  - `start_date` string, required
  - `totals` UsageTotals, required — Grand totals over the filtered window.
    - `avg_latency_ms` number, nullable, required
    - `cache_read_tokens` integer, required
    - `cache_write_1h_tokens` integer, required
    - `cache_write_tokens` integer, required
    - `completion_tokens` integer, required
    - `cost` number, required
    - `error_count` integer, required
    - `prompt_tokens` integer, required
    - `request_count` integer, required
    - `total_tokens` integer, required
    - `unpriced_requests` integer

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-03** `18e6c426d62c` — 6 info
  - added the new optional `query` request parameter `dimensions`
  - added the new optional `query` request parameter `provider`
  - added the new optional `query` request parameter `source_label`
  - added the required property `by_endpoint` to the response with the `200` status
  - …2 more
- **2026-07-24** `fa738a5ab2a5` — 2 info
  - added the new optional `query` request parameter `counts_toward_budget`
  - added the new optional `query` request parameter `priced`
- **2026-07-23** `2a163c690f59` — 4 info
  - added the new optional `query` request parameter `api_key_id`
  - added the new optional `query` request parameter `source`
  - added the optional property `totals/unpriced_requests` to the response with the `200` status
  - added the required property `by_source` to the response with the `200` status
- **2026-07-23** `eba5b612f28e` — 1 info
  - added the required property `totals/cache_write_1h_tokens` to the response with the `200` status
- **2026-07-21** `b58ece3074c8` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mozilla-ai/apis/otari/changes/v1/usage/summary/get.md)

---

[API](https://skmtc.dev/mozilla-ai/apis/otari.md) · [All operations](https://skmtc.dev/mozilla-ai/apis/otari/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mozilla-ai/otari/revisions/d3b3a0f427b2/schema)