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

Как вызвать

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

Параметры

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

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

Ответ

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

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

К строкам добавляется ключ разбивки: 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 без второй разбивки возвращают каждый день или час периода, пустые — нулями. Удобно строить график без заполнения дыр.

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

• Точность до часа. Данные собраны по часам, поэтому 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.

Примеры

curl "https://api.aitunnel.ru/v1/aitunnel/usage?period=month" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

curl "https://api.aitunnel.ru/v1/aitunnel/usage?period=last_month&group_by=model" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

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

curl "https://api.aitunnel.ru/v1/aitunnel/usage?period=30d&group_by=user" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

import requests

usage = requests.get(
    "https://api.aitunnel.ru/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"]} запросов')

Ошибки

{
  "error": {
    "message": "Некорректный group_by «week». Допустимо одно значение из day, hour и одно из model, endpoint, user через запятую, например day,model.",
    "code": 400
  }
}