---
title: "Get how many tokens a project has spent on the AI Gateway, per key, minute, hour or day, and model"
method: GET
path: "/project/{project}/ai-gateway/usage"
tags: ["AIGateway"]
---

# Get how many tokens a project has spent on the AI Gateway, per key, minute, hour or day, and model

`GET /project/{project}/ai-gateway/usage`

## Request

- Base URL: `https://api.aiven.io/v1`
- URL: `https://api.aiven.io/v1/project/{project}/ai-gateway/usage`
- Auth: HTTP bearer and OAuth 2
  - Authorization code: `https://console.aiven.io/oauth/authorize`
  - Token URL: `https://api.aiven.io/v1/oauth2/token` scopes: `projects:read`

> This endpoint **may be changed or removed at any time**. Don't use it in production environments.

A row with no `key_id` is the whole project's usage for that time bucket and model, and is reported only when no `key_id` is asked for. A bucket nothing was spent on is left out rather than reported as zeroes. Both ends of the range must fall on a UTC minute. A bucket that the range cuts holds only the usage inside the range. A range on whole UTC hours at hour or day granularity is read from the hourly totals, which keep the whole history but take up to about 15 minutes to show recent usage. Any other range is read from the requests themselves, which are up to date but kept for 3 months only. The cost is an estimate at the rates the catalogue lists now, not what was charged at the time: the input outside the prompt cache, the tokens read from and written to it, and the output, each at a rate of its own. A model the catalogue no longer lists keeps its usage and is reported with no cost at all.

## Path parameters

- `project` string, required

## Query parameters

- `key_id` string
- `starting_time` string
- `ending_time` string
- `granularity` 'minute' | 'hour' | 'day'

## Response `200`

Response

- AIGatewayUsageGetResponse: AIGatewayUsageGetResponse
  - `usage` object[], required: AI Gateway usage per key, time bucket and model
    - `cache_read_tokens` integer, required: Share of the input tokens served from the prompt cache
    - `cache_write_tokens` integer, required: Share of the input tokens written to the prompt cache
    - `estimated_cost_usd` number: Estimate at the rates the catalogue lists now, or null for a model it no longer lists
    - `input_tokens` integer, required: Tokens sent to the model, prompt cache included
    - `key_id` string: Key the usage is attributed to, or null for the whole project in that time bucket
    - `model_name` string, required: Name of the model
    - `output_tokens` integer, required: Tokens returned by the model
    - `request_count` integer, required: Number of requests made to the model
    - `timestamp` string, required: Start of the UTC minute, hour or day the usage falls in, per the granularity asked for
    - `total_tokens` integer, required: Tokens sent and returned
    - `uncached_input_tokens` integer, required: Share of the input tokens that missed the prompt cache

## Other responses

- `400`: The granularity is not minute, hour or day, or the time range is unreadable, off the minute, reversed, longer than the maximum, older than the requests are kept for, or matches more usage than one response holds
- `403`: AI Gateway is not enabled for this organization
- `404`: Key not found
- `503`: The key cannot be looked up

## Changes

- **2026-10-14** `890113a87c87`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/aiven/apis/aiven-api-documentation/changes/project/:project/ai-gateway/usage/get.md)

---

[API](https://skmtc.dev/aiven/apis/aiven-api-documentation.md) - [All operations](https://skmtc.dev/aiven/apis/aiven-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/aiven/apis/aiven-api-documentation/revisions/562453405db0?raw)