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

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

Попробовать

GET/v1/usage

API-ключСохранить ключ в localStorage этого браузера

Параметры и ответ

GET/v1/usage

Authorization

AuthorizationRequiredBearer <token>

API-ключ в формате sk-gw- + 32 hex. Создаётся в дашборде на /keys.

In: header

Query Parameters

periodstring

Шорткат периода. today = с 00:00 UTC текущих суток. 24h = последние 24ч. 7d/30d = последние N суток. mtd = с 1-го числа текущего месяца UTC. Несовместим с from/to.

Value in: "today" | "24h" | "7d" | "30d" | "mtd"

fromstring

Начало периода, ISO 8601. Если задан — to тоже обязателен.

Format: "date-time"

tostring

Конец периода, ISO 8601. Если задан — from тоже обязателен.

Format: "date-time"

granularitystring

Если указан — в ответе появится массив buckets с агрегатами по этому шагу.

Value in: "hour" | "day"

curl -X GET "https://api.hubris.pw/v1/usage?period=today&from=2019-08-24T14%3A15%3A22Z&to=2019-08-24T14%3A15%3A22Z&granularity=hour" \
  -H "Authorization: Bearer <token>"

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

{
  "object": "usage",
  "period": {
    "from": "2026-05-13T00:00:00.000Z",
    "to": "2026-05-14T00:00:00.000Z",
    "shortcut": "today"
  },
  "scope": {
    "key_id": "1e779c8a-6786-4c89-b7c3-a6666f5fd6b5",
    "key_prefix": "sk-gw-a1b2...c3d4"
  },
  "totals": {
    "requests": 137,
    "prompt_tokens": 18420,
    "completion_tokens": 9610,
    "total_tokens": 28030,
    "cost_rub": 42.17,
    "cost_kopecks": "4217"
  },
  "granularity": "hour",
  "buckets": [
    {
      "bucket": "2026-05-14T00:00:00.000Z",
      "cost_rub": 12.34,
      "cost_kopecks": "1234",
      "requests": 42
    }
  ]
}

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

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

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

Примеры

Расход за последние 24 часа:

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

Ответ:

{
  "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": 300,
    "completion_tokens": 130,
    "total_tokens": 430,
    "cost_rub": 54.76,
    "cost_kopecks": "5476"
  },
  "granularity": null,
  "buckets": null
}

Расход за сегодня (с 00:00 UTC):

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

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

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"

С разбивкой по дням (для графика):

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

Тогда в ответе появится buckets:

{
  "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 }
  ]
}

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']} ₽")

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} ₽`);

Заметки про точность

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

Что дальше

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

GET /v1/usage