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

# Get Usages

`GET /v1/usage`

## Request

- The document declares no server URL.
- Auth: HTTP bearer

Get daily usage buckets for the current user.

## Query parameters

- `offset` integer: Number of usage buckets to skip.
- `limit` integer: Maximum number of usage buckets to return.
- `start_time` integer, required: Start time as Unix timestamp.
- `end_time` integer, required: End time as Unix timestamp.
- `endpoint` '/v1/audio/transcriptions' | '/v1/chat/completions' | '/v1/embeddings' | '/v1/ocr' | '/v1/rerank' | '/v1/search'
- `model` string, nullable: Router name to filter usage by.
- `key_id` integer, nullable: Key ID to filter usage by.

## Response `200`

Successful Response

- UsagesResponse
  - `object` 'list': Type of the object.
  - `total` integer, required: Total number of usage buckets.
  - `offset` integer, required: Offset of the usage buckets list.
  - `limit` integer, required: Limit of the usage buckets list.
  - `data` UsageBucketResponse[], required: List of daily usage buckets.
    - `object` 'usage.bucket': Type of the object.
    - `start_time` integer, required: UTC start of the day bucket, as Unix timestamp.
    - `end_time` integer, required: UTC exclusive end of the day bucket, as Unix timestamp.
    - `prompt_tokens` integer, required: Sum of prompt tokens in the bucket.
    - `completion_tokens` integer, required: Sum of completion tokens in the bucket.
    - `total_tokens` integer, required: Sum of total tokens in the bucket.
    - `cost` number, required: Sum of request costs in the bucket.
    - `requests` integer, required: Number of successful requests in the bucket.
    - `impacts` ApiInfrastructureFastapiSchemasUsageEnvironmentalImpacts
      - `kWh` number: Energy consumption in kWh.
      - `kgCO2eq` number: Carbon footprint in kgCO2eq (global warming potential).

## Other responses

- `401`: Invalid authentication scheme.<br>Invalid API key.
- `403`: Your account has expired. Please contact support to renew your account.
- `422`: Validation Error

## Changes

- **2026-09-29** `2f7a4a0aac8f`: 1 info
  - endpoint added
- **2026-09-29** `da70d9cd1957`: 1 breaking
  - api path removed without deprecation
- **2026-09-28** `87472bc2094f`: 1 warning, 1 info
  - deleted the `query` request parameter `models`
  - added the new optional `query` request parameter `model`
- **2026-09-21** `5fdbd3614b8c`: 8 breaking, 4 warning, 11 info
  - the `query` request parameter `end_time` became required
  - the `query` request parameter `start_time` became required
  - `query` request parameter `end_time` list-of-types was narrowed by removing types `null`
  - `query` request parameter `start_time` list-of-types was narrowed by removing types `null`
  - …19 more
- **2026-08-27** `1627e468291c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/betagouv/apis/opengatellm/changes/v1/usage/get.md)

---

[API](https://skmtc.dev/betagouv/apis/opengatellm.md) - [All operations](https://skmtc.dev/betagouv/apis/opengatellm/llms.txt) - [OpenAPI document](https://skmtc.dev/betagouv/apis/opengatellm/revisions/2f7a4a0aac8f?raw)