---
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
(top rows plus a reconciling ``other`` fold), and a UTC-bucketed time series.

## 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')
- `bucket` 'hour' | 'day' — Time-series granularity: 'hour' or 'day'

## Response `200`

Successful Response

- UsageSummary — Aggregate spend/volume for the Usage & analytics page.
  - `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_model` 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_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

## Other responses

- `422` — Validation Error

## Changes

- **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/66056c7fd2e2/schema)