Возвращает итоговый расход (рубли, копейки, токены, число запросов) по тому API-ключу, которым сделан запрос. Расход других ключей того же аккаунта сюда не попадёт — это специально, чтобы один скомпрометированный ключ не показывал общий бюджет.

По умолчанию — последние 24 часа. Период задаётся либо шорткатом ?period=, либо явными ?from=&to= (ISO 8601, UTC). Опциональный ?granularity=hour|day добавит массив buckets для построения графика.

Эндпоинт

GEThttps://api.hubris.pw/v1/usage

Заголовки:

Header	Значение
`Authorization`	`Bearer sk-gw-...` (обязательно)

Query-параметры

Параметр	Тип	По умолчанию	Описание
`period`	`"today" \| "24h" \| "7d" \| "30d" \| "mtd"`	`"24h"`	Шорткат периода. Взаимоисключающий с `from`/`to`.
`from`	`string` (ISO 8601, UTC)	—	Начало периода включительно. Требует `to`.
`to`	`string` (ISO 8601, UTC)	—	Конец периода включительно. Требует `from`.
`granularity`	`"hour" \| "day"`	—	Если задано — в ответе появится `buckets[]` с поминутной разбивкой. Без `granularity` ответ только totals.

period и from/to нельзя передавать одновременно — будет 400 invalid_request. Максимальный диапазон при явных датах — 365 дней.

Шорткаты периода

`period`	Что считается
`today`	С 00:00 UTC текущих суток до сейчас.
`24h`	Последние 24 часа (по умолчанию).
`7d`	Последние 7 суток.
`30d`	Последние 30 суток.
`mtd`	С 1-го числа текущего месяца (UTC).

Минимальный пример

curl -s https://api.hubris.pw/v1/usage \
-H "Authorization: Bearer $HUBRIS_API_KEY"

curl -s https://api.hubris.pw/v1/usage \-H "Authorization: Bearer $HUBRIS_API_KEY"

import os, requests

r = requests.get(
  "https://api.hubris.pw/v1/usage",
  params={"period": "7d", "granularity": "day"},
  headers={"Authorization": f"Bearer {os.environ['HUBRIS_API_KEY']}"},
)
data = r.json()
print(f"Расход за 7 дней: {data['totals']['cost_rub']} ₽")

import os, requestsr = requests.get(  "https://api.hubris.pw/v1/usage",  params={"period": "7d", "granularity": "day"},  headers={"Authorization": f"Bearer {os.environ['HUBRIS_API_KEY']}"},)data = r.json()print(f"Расход за 7 дней: {data['totals']['cost_rub']} ₽")

const r = await fetch(
"https://api.hubris.pw/v1/usage?period=7d&granularity=day",
{ headers: { Authorization: `Bearer ${process.env.HUBRIS_API_KEY}` } },
);
const data = await r.json();
console.log(`Расход за 7 дней: ${data.totals.cost_rub} ₽`);

const r = await fetch("https://api.hubris.pw/v1/usage?period=7d&granularity=day",{ headers: { Authorization: `Bearer ${process.env.HUBRIS_API_KEY}` } },);const data = await r.json();console.log(`Расход за 7 дней: ${data.totals.cost_rub} ₽`);

Ответ

{
  "object": "usage",
  "period": {
    "from": "2026-05-13T09:29:31.192Z",
    "to": "2026-05-14T09:29:31.192Z",
    "shortcut": null
  },
  "scope": {
    "key_id": "31fb0d0d-ac86-4f72-815b-bdefd5978747",
    "key_prefix": "sk-gw-758f...d4e3"
  },
  "totals": {
    "requests": 2,
    "prompt_tokens": 6000,
    "completion_tokens": 130,
    "total_tokens": 6130,
    "cache_read_tokens": 198000,
    "cache_write_tokens": 0,
    "reasoning_tokens": 0,
    "cache_hit_rate": 0.97,
    "cache_savings_kopecks": "48150",
    "cache_savings_rub": 481.5,
    "cost_rub": 54.76,
    "cost_kopecks": "5476"
  },
  "granularity": null,
  "buckets": null
}

Поля ответа

Поле	Тип	Описание
`object`	`"usage"`	Тип объекта.
`period.from`	`string` (ISO 8601 UTC)	Начало периода включительно.
`period.to`	`string` (ISO 8601 UTC)	Конец периода включительно.
`period.shortcut`	`string \| null`	Если использовался шорткат — его имя; иначе `null`.
`scope.key_id`	`string` (UUID)	ID ключа, по которому собирается расход.
`scope.key_prefix`	`string`	Видимый префикс ключа для логов.
`totals.requests`	`integer`	Кол-во запросов за период.
`totals.prompt_tokens`	`integer`	Сумма входных токенов.
`totals.completion_tokens`	`integer`	Сумма выходных токенов.
`totals.total_tokens`	`integer`	Сумма обоих.
`totals.cache_read_tokens`	`integer`	Токены, прочитанные из кеша (дешевле обычного входа).
`totals.cache_write_tokens`	`integer`	Токены записи кеша (дороже обычного входа).
`totals.reasoning_tokens`	`integer`	Токены рассуждения — подмножество `completion_tokens`, не прибавляйте их отдельно.
`totals.cache_hit_rate`	`number` (0..1)	Доля попаданий в кеш за период.
`totals.cache_savings_kopecks`	`string`	Сколько кеш сэкономил за период (нетто), в копейках.
`totals.cache_savings_rub`	`number`	То же значение в рублях.
`totals.cost_rub`	`number`	Итоговая стоимость в рублях. Эквивалент `cost_kopecks / 100`.
`totals.cost_kopecks`	`string`	Итоговая стоимость в копейках. Строка — чтобы не терять точность на больших суммах (`BigInt`).
`granularity`	`"hour" \| "day" \| null`	Если в запросе был задан — повторяется здесь.
`buckets[]`	`array \| null`	Если `granularity` задан — массив значений по интервалам.
`buckets[].bucket`	`string` (ISO 8601)	Начало интервала.
`buckets[].cost_rub`	`number`	Стоимость интервала.
`buckets[].cost_kopecks`	`string`	Стоимость в копейках.
`buckets[].requests`	`integer`	Кол-во запросов в интервале.

Всего входных токенов = prompt_tokens + cache_read_tokens + cache_write_tokens. reasoning_tokens входят в completion_tokens, не прибавляйте их отдельно.

С разбивкой по дням

С granularity в ответе появится buckets:

curl -s -H "Authorization: Bearer $HUBRIS_API_KEY" \
  "https://api.hubris.pw/v1/usage?period=7d&granularity=day"

{
  "granularity": "day",
  "buckets": [
    { "bucket": "2026-05-07T00:00:00.000Z", "cost_rub": 0,     "cost_kopecks": "0",    "requests": 0 },
    { "bucket": "2026-05-08T00:00:00.000Z", "cost_rub": 0,     "cost_kopecks": "0",    "requests": 0 },
    { "bucket": "2026-05-14T00:00:00.000Z", "cost_rub": 54.76, "cost_kopecks": "5476", "requests": 2 }
  ]
}

Произвольный диапазон

curl -s -H "Authorization: Bearer $HUBRIS_API_KEY" \
  "https://api.hubris.pw/v1/usage?from=2026-04-01T00:00:00Z&to=2026-05-01T00:00:00Z"

Точность

cost_kopecks — строка, чтобы не терять точность на больших суммах (JavaScript Number не выдержит, если когда-нибудь биллим сильно дорогих агентов). Парсить через BigInt.
cost_rub — то же значение, делённое на 100, для удобства отображения.
Время в UTC. Если нужно «сутки по Москве» — пришлите явные from/to, конвертированные на стороне клиента.

HTTP-коды

Код	Когда
`200`	Успешный ответ.
`400`	Конфликт `period` + `from`/`to`, диапазон > 365 дней, неверный формат даты.
`401`	Ключ отсутствует / отозван / невалиден.
`429`	Превышен дневной лимит на ключе.

Что дальше

Биллинг — как формируется итоговая стоимость и из чего складываются токены.
Цены — формула расчёта.
В UI: страница /usage в дашборде с фильтрами по модели, ключу и статусу + CSV-экспорт.

Обновлено: 24 мая 2026 г.

GET /v1/usage