---
title: "Расход по API-ключу за период"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Расход по API-ключу за период

`GET /v1/usage`

## Request

- Base URL: `https://api.hubris.pw`
- URL: `https://api.hubris.pw/v1/usage`
- Auth: HTTP bearer

Возвращает итоговые расходы (рубли + копейки + токены + количество запросов) по тому API-ключу, которым сделан запрос; OAuth-токену — по всему подключению приложения (токен меняется каждый час, сумма — по всем токенам подключения). По умолчанию — последние 24 часа. Можно передать шорткат `?period=` либо явные `?from=&to=` (ISO 8601, UTC). Опциональный `?granularity=` добавит массив `buckets` для построения графика.

## Query parameters

- `period` 'today' | '24h' | '7d' | '30d' | 'mtd': Шорткат периода. `today` = с 00:00 UTC текущих суток. `24h` = последние 24ч. `7d`/`30d` = последние N суток. `mtd` = с 1-го числа текущего месяца UTC. Несовместим с `from`/`to`.
- `from` string, date-time: Начало периода, ISO 8601. Если задан — `to` тоже обязателен.
- `to` string, date-time: Конец периода, ISO 8601. Если задан — `from` тоже обязателен.
- `granularity` 'hour' | 'day': Если указан — в ответе появится массив `buckets` с агрегатами по этому шагу.
- `key_id` string, uuid: Только management-ключом: сузить аккаунт-скоуп до одного API-ключа.
- `group_by` 'key' | 'model': Только management-ключом: добавить разбивку `by_key` или `by_model`.

## Response `200`

Расход по ключу за указанный период.

- UsageResponse
  - `object` 'usage', required
  - `period` object, required
    - `from` string, date-time, required: Начало периода (UTC, ISO 8601). Включительно.
    - `to` string, date-time, required: Конец периода (UTC, ISO 8601). Включительно.
    - `shortcut` 'today' | '24h' | '7d' | '30d' | 'mtd', nullable, required: Шорткат, если запрос был сделан через `?period=`. Иначе null.
  - `scope` union, required: Обычный ключ: расход только по нему. OAuth-токен: расход всего подключения приложения, `key_id` — текущий токен. Management-ключ: весь аккаунт (`account: true`), опционально суженный параметром `key_id`.
    - object
      - `key_id` string, uuid, required
      - `key_prefix` string, required
    - object
      - `account` true, required
      - `key_id` string, uuid, nullable, required
  - `totals` object, required
    - `requests` integer, required
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `cost_rub` number, required: Итоговая стоимость за период в рублях. Эквивалент cost_kopecks/100.
    - `cost_kopecks` string, required: Итоговая стоимость в копейках (строка для точности при сериализации bigint).
    - `cache_read_tokens` integer, required
    - `cache_write_tokens` integer, required
    - `reasoning_tokens` integer, required
    - `cache_hit_rate` number, required
    - `cache_savings_kopecks` string, required
    - `cache_savings_rub` number, required
  - `granularity` 'hour' | 'day', nullable, required: Если `granularity` был задан, тут он же. Иначе null.
  - `buckets` UsageBucket[], nullable, required: Точки графика. Null, если `granularity` не запрошен.
    - `bucket` string, date-time, required: Начало интервала в ISO 8601 (UTC).
    - `cost_rub` number, required: Стоимость за интервал в рублях. cost_kopecks/100.
    - `cost_kopecks` string, required: Стоимость за интервал в копейках (строка — чтобы пережить JSON без потери точности).
    - `requests` integer, required
  - `by_key` object[], nullable: Разбивка по ключам аккаунта (`group_by=key`, только management-ключом). Иначе отсутствует.
    - `key_id` string, uuid, nullable, required
    - `key_prefix` string, nullable, required
    - `name` string, nullable, required
    - `requests` integer, required
    - `total_tokens` integer, required
    - `cost_kopecks` string, required: Копейки строкой — как в totals.
  - `by_model` object[], nullable: Разбивка по моделям (`group_by=model`, только management-ключом). Иначе отсутствует.
    - `model` string, required
    - `requests` integer, required
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `cost_kopecks` string, required: Копейки строкой — как в totals.

## Other responses

- `400`: Невалидные параметры периода (range_invalid / range_too_long / period_invalid).
- `401`: Невалидный или отсутствующий API-ключ.
- `429`: Превышен дневной лимит ключа.

---

[API](https://skmtc.dev/hubris/apis/hubris-api.md) · [All operations](https://skmtc.dev/hubris/apis/hubris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hubris/apis/hubris-api/revisions/79ea91ed8f10?raw)