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

# List Usage

`GET /v1/usage`

List usage logs ordered by timestamp (most recent first).

Supports optional filters for time range, user, status, model, endpoint,
provider, source, and session (``source_label``).
Paginated via skip/limit. The return shape is a bare JSON array; external
billing/analytics consumers depend on this, so the total row count for a
paginated UI is served separately by ``GET /v1/usage/count`` rather than
wrapped in an envelope here. Timestamps accept either ISO 8601 strings or
Unix epoch seconds (numeric).

## 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
- `skip` integer
- `limit` integer

## Response `200`

Successful Response

- UsageEntry[]
  - `api_key_id` string, nullable, required
  - `billing_meters` object, nullable, required
  - `cache_read_tokens` integer, nullable, required
  - `cache_write_1h_tokens` integer, nullable, required
  - `cache_write_tokens` integer, nullable, required
  - `completion_tokens` integer, nullable, required
  - `cost` number, nullable, required
  - `counts_toward_budget` boolean, required
  - `endpoint` string, required
  - `error_message` string, nullable, required
  - `id` string, required
  - `latency_ms` integer, nullable, required
  - `model` string, required
  - `pricing_breakdown` object[], nullable, required
  - `prompt_tokens` integer, nullable, required
  - `provider` string, nullable, required
  - `source` string, required
  - `source_label` string, nullable, required
  - `status` string, required
  - `timestamp` string, required
  - `total_tokens` integer, nullable, required
  - `user_id` string, nullable, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-03** `18e6c426d62c` — 2 info
  - added the new optional `query` request parameter `provider`
  - added the new optional `query` request parameter `source_label`
- **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` — 5 info
  - added the new optional `query` request parameter `api_key_id`
  - added the new optional `query` request parameter `source`
  - added the required property `items/counts_toward_budget` to the response with the `200` status
  - added the required property `items/source` to the response with the `200` status
  - …1 more
- **2026-07-23** `eba5b612f28e` — 3 info
  - added the required property `items/billing_meters` to the response with the `200` status
  - added the required property `items/cache_write_1h_tokens` to the response with the `200` status
  - added the required property `items/pricing_breakdown` to the response with the `200` status
- **2026-07-21** `9da977999634` — 4 info
  - added the new optional `query` request parameter `endpoint`
  - added the new optional `query` request parameter `model`
  - added the new optional `query` request parameter `status`
  - added the required property `items/latency_ms` to the response with the `200` status

[Full history](https://skmtc.dev/mozilla-ai/apis/otari/changes/v1/usage/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)