---
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 and user. Paginated via skip/limit.
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
- `skip` integer
- `limit` integer

## Response `200`

Successful Response

- UsageEntry[]
  - `api_key_id` string, nullable, required
  - `cache_read_tokens` integer, nullable, required
  - `cache_write_tokens` integer, nullable, required
  - `completion_tokens` integer, nullable, required
  - `cost` number, nullable, required
  - `endpoint` string, required
  - `error_message` string, nullable, required
  - `id` string, required
  - `model` string, required
  - `prompt_tokens` integer, nullable, required
  - `provider` 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-07-14** `0ad4e5f1cc3e` — 1 info
  - the endpoint scheme security `ApiKeyAuth` was added to the API
- **2026-06-23** `0f71cbdfff44` — 2 info
  - added the required property `items/cache_read_tokens` to the response with the `200` status
  - added the required property `items/cache_write_tokens` to the response with the `200` status
- **2026-04-17** `0f43605bdc13` — 2 breaking, 1 info
  - removed the required property `items/cache_read_tokens` from the response with the `200` status
  - removed the required property `items/cache_write_tokens` from the response with the `200` status
  - the endpoint scheme security `ApiKeyAuth` was removed from the API

[Change 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/0ad4e5f1cc3e/schema)