Расход и использование

Сколько потрачено за период: запросы, рубли, токены, время ответа. С разбивкой по дням, часам, моделям и методам API. Метод AITUNNEL, не OpenAI.

Эндпоинт
Авторизация
API-ключ или ключ управления с правом usage:read

Чей расход придёт в ответе, зависит от ключа:

Чем авторизоватьсяЧто считается
API-ключРасход этого ключа
Ключ управления с правом usage:readРасход всего аккаунта: все ключи и Студия. Параметр key_id оставляет один ключ

Как вызвать

curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/usage?period=7d&group_by=day" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

Параметры

Все необязательные. Без параметров — последние 30 дней в UTC, одной суммой.

ПараметрСмысл
periodtoday, yesterday, 7d, 30d (по умолчанию), 90d, month (с 1-го числа), last_month (прошлый месяц целиком). Это календарные дни в timezone, текущий день входит
from, toСвой период вместо period. Дата YYYY-MM-DD — целые сутки, to включительно. Время с поясом (2026-10-31T00:00:00Z) — to не включается. Без to — до текущего момента
timezoneЧасовой пояс IANA для границ дней и для group_by=day, по умолчанию UTC. Например Europe/Moscow
group_byday, hour, model, endpoint, user. Можно два через запятую: одно из day/hour и одно из model/endpoint/user, например day,model
modelТолько эта модель, имя целиком, например gpt-5-nano
endpointТолько этот метод API: /v1/chat/completions, /v1/embeddings, /v1/images/generations и так далее
appТолько запросы этого приложения: значение X-Title или домен из HTTP-Referer, studio — Студия, playground — Песочница. none — запросы, которые приложение не назвали
userТолько запросы с этим user (или metadata.user_id у Messages), значение целиком. В ответе появляется поле user. См. Расход по user
session_idТолько запросы этой сессии, значение целиком: сколько стоил один диалог или запуск агента. В ответе появляется поле session_id. Как и user, считается по журналу запросов: период до 92 дней
key_idТолько этот API-ключ: номер из GET /aitunnel/keys. Работает с ключом управления; с API-ключом — 403
includelatency — добавить к суммам время ответа с перцентилями

period и from/to вместе не передаются. to без from не принимается.

Ответ

JSON
{
  "object": "usage",
  "period": {
    "from": "2026-10-25T00:00:00.000Z",
    "to": "2026-10-28T00:00:00.000Z",
    "timezone": "UTC",
    "preset": null
  },
  "group_by": ["day"],
  "totals": {
    "requests": 61,
    "cost_rub": 14.37,
    "tool_cost_rub": 0.5,
    "log_cost_rub": 0,
    "cache_savings_rub": 1.92,
    "discount_savings_rub": 0,
    "avg_duration_ms": 2140,
    "usage": {
      "prompt_tokens": 182400,
      "completion_tokens": 21350,
      "cached_tokens": 96000,
      "cache_write_tokens": 0,
      "reasoning_tokens": 8120,
      "audio_input_tokens": 0,
      "audio_output_tokens": 0,
      "video_input_tokens": 0,
      "image_output_tokens": 0,
      "web_search_requests": 5,
      "video_seconds": 0,
      "speech_characters": 0,
      "transcription_seconds": 0,
      "embedding_inputs": 120,
      "rerank_documents": 0
    }
  },
  "data": [
    { "date": "2026-10-25", "requests": 24, "cost_rub": 6.1, "...": "поля как в totals" },
    { "date": "2026-10-26", "requests": 0, "cost_rub": 0, "...": "нули, запросов не было" },
    { "date": "2026-10-27", "requests": 37, "cost_rub": 8.27, "...": "" }
  ]
}
ПолеСмысл
periodПериод, который посчитан на самом деле: границы после округления, пояс и preset (имя period или null для своего периода)
group_byКакие разбивки применены, пустой список — без разбивки
totalsИтог за весь период
dataСтроки разбивки. Нет, если group_by не задан

В totals и в каждой строке data одни и те же поля:

ПолеСмысл
requestsЧисло запросов
cost_rubСписано, ₽
tool_cost_rubИз них за серверные инструменты: веб-поиск и поиск по базе знаний, ₽
log_cost_rubИз них за хранение запросов и ответов, ₽
cache_savings_rubСколько сэкономил кэш промпта, ₽
discount_savings_rubСколько сэкономила персональная скидка, ₽
avg_duration_msСреднее время запроса, мс, или null, если запросов нет
usageТокены и единицы: prompt_tokens, completion_tokens, cached_tokens, cache_write_tokens, reasoning_tokens, audio_input_tokens, audio_output_tokens, video_input_tokens, image_output_tokens, web_search_requests, а также объём нетокенных методов: video_seconds (секунды видео), speech_characters (символы озвученного текста), transcription_seconds (секунды аудио), embedding_inputs (входы эмбеддингов), rerank_documents (документы rerank). Все поля есть всегда, если не было — 0

К строкам добавляется ключ разбивки: date (2026-10-25, день в timezone), start (час в UTC, 2026-10-25T14:00:00Z), model, endpoint (/v1/chat/completions), user.

  • Строки идут по порядку: по времени, затем по убыванию расхода. Только model или endpoint — самые затратные первыми.
  • group_by=day и group_by=hour без второй разбивки возвращают каждый день или час периода, пустые — нулями. Удобно строить график без заполнения дыр.

Время ответа

С include=latency в totals и в каждой строке data появляется объект latency:

JSON
"latency": {
  "duration": { "count": 61, "avg_ms": 2140, "p50_ms": 1830, "p95_ms": 6120 },
  "ttft": { "count": 48, "avg_ms": 412, "p50_ms": 350, "p95_ms": 980 }
}
ПолеСмысл
durationВремя всего ответа
ttftВремя до первого токена. Только потоковые запросы
countУ скольких запросов это время записано
avg_msСреднее, мс. Точное
p50_ms, p95_msМедиана и 95-й перцентиль, мс. Оценка по гистограмме: от точного значения отличается не больше чем примерно на 12%

Если запросов не было, count равен 0, остальное — null. Параметр работает с любым ключом и с любой разбивкой.

Что нужно знать

  • Точность до часа. Данные собраны по часам, поэтому from округляется вниз до часа, to вверх. Фактический период — в period.
  • Пояса. Поддерживаются пояса со сдвигом, кратным часу (Europe/Moscow, Asia/Dubai). Для Asia/Kolkata и подобных — ближайший.
  • Лимиты. Период — до 366 дней, group_by=hour — до 31 дня, в ответе — до 5000 строк. Если не помещается, ответ 400 с подсказкой.
  • Будущее не считается: to обрезается текущим часом.

Расход по user

Подробно, с примерами и счётом клиенту — Пользователи вашего сервиса. Если в запросах вы передаёте свой идентификатор пользователя (user в теле любого платного метода, metadata.user_id в Messages), расход можно считать по нему: group_by=user — строка на каждого, user=customer-42 — только один.

  • Считаются только запросы, где user был передан. Остальные в такой выборке не участвуют, поэтому итог может быть меньше общего расхода.
  • Данные берутся из журнала запросов, он хранится около трёх месяцев, а поле пишется только с момента его появления. Период — до 92 дней, иначе 400.
  • Если пользователей больше 5000 или запрос слишком тяжёлый, ответ 400: сузьте период или добавьте фильтр model или endpoint.

Примеры

Сколько потрачено в этом месяце

bash
curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/usage?period=month" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

Расход по моделям за прошлый месяц

bash
curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/usage?period=last_month&group_by=model" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

Расход по дням и моделям за период, по московскому времени

bash
curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/usage?from=2026-10-01&to=2026-10-15&group_by=day,model&timezone=Europe/Moscow" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

Расход по вашим пользователям за 30 дней

bash
curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/usage?period=30d&group_by=user" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

Расход всего аккаунта за месяц, ключом управления

bash
curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/usage?period=month&group_by=model" \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

Расход одного ключа по дням со временем ответа, ключом управления

bash
curl "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/usage?period=7d&group_by=day&key_id=4217&include=latency" \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

Python: топ моделей по расходу

python
import requests

usage = requests.get(
    "https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/usage",
    params={"period": "30d", "group_by": "model"},
    headers={"Authorization": "Bearer sk-aitunnel-xxx"},
).json()

for row in sorted(usage["data"], key=lambda r: -r["cost_rub"])[:5]:
    print(f'{row["model"]}: {row["cost_rub"]} ₽, {row["requests"]} запросов')

Ошибки

КодСмысл
400Неверный параметр: период, дата, пояс, group_by, endpoint, include, key_id; период пустой или слишком большой
401Нет ключа или он неверный
403key_id передан с API-ключом, или у ключа управления нет права usage:read
400
{
  "error": {
    "code": 400,
    "type": "invalid_request",
    "message": "Некорректный group_by «week». Допустимо одно значение из day, hour и одно из model, endpoint, user через запятую, например day,model.",
    "request_id": "req-0J9fQk2vXc8LrT1mNbZa4e"
  }
}