tkbk.io
▤ Справочник

Usage Query API

Read-only токен ro_xxx и GET /v1/usage: баланс, лимиты и расход по моделям. Параметры period=day|month|total, примеры curl, Python, Node и алерт на остаток.

Обновлено 21 июл. 2026 г.⏱ 7 мин
#usage#статистика#баланс#ro_token#мониторинг#cron

Usage Query API отдаёт баланс, лимиты и расход по моделям в JSON. Работает по отдельному read-only токену ro_… — им нельзя делать запросы к моделям и тратить деньги, только читать статистику.

#Read-only токен

ℹ
ro_ ≠ cr_
Токен ro_… даёт доступ только к /v1/usage. Его безопасно класть в дашборды, мониторинг и cron — он не может отправлять запросы к моделям и списывать баланс.
  1. 1
    Запросите ro-токен

    Напишите @nukind — read-only токен выдаётся к вашему аккаунту.

  2. 2
    Храните как секрет

    Держите ro_… в переменной окружения, а не в коде.

  3. 3
    Опрашивайте по расписанию

    Дёргайте /v1/usage из cron или дашборда — тело запросов не логируется, статистика свежая.

#Запрос

ПараметрЗначенияСмысл
periodday · month · totalОкно агрегации расхода
МетодGETТолько чтение
URLhttps://api.tkbk.io/v1/usageЕдиный endpoint статистики
ЗаголовокAuthorization: Bearer ro_…Read-only токен
GET /v1/usage
curl -s "https://api.tkbk.io/v1/usage?period=day" \
  -H "Authorization: Bearer ro_your_readonly_token"

#Формат ответа

ответ /v1/usage
{
  "balance_usd": 42.13,
  "currency": "USD",
  "period": "day",
  "limits": {
    "daily_usd": 45,
    "daily_used_usd": 2.87,
    "window_minutes": 300,
    "rpm": 30
  },
  "usage": {
    "input_tokens": 128400,
    "output_tokens": 43120,
    "cache_tokens": 21000,
    "requests": 512,
    "cost_usd": 2.87
  },
  "by_model": [
    { "model": "claude-sonnet-5", "requests": 340, "input_tokens": 90000, "output_tokens": 30000, "cost_usd": 2.10 },
    { "model": "gpt-5-mini", "requests": 172, "input_tokens": 38400, "output_tokens": 13120, "cost_usd": 0.77 }
  ]
}

#Python

usage.py
import os
import requests

TOKEN = os.environ["TKBK_RO_TOKEN"]

r = requests.get(
    "https://api.tkbk.io/v1/usage",
    params={"period": "month"},
    headers={"Authorization": "Bearer " + TOKEN},
    timeout=10,
)
r.raise_for_status()
data = r.json()

print("Баланс USD:", round(data["balance_usd"], 2))
for m in data["by_model"]:
    print(m["model"], "->", m["cost_usd"], "USD")

#Node.js

usage.mjs
const TOKEN = process.env.TKBK_RO_TOKEN;

const res = await fetch("https://api.tkbk.io/v1/usage?period=total", {
  headers: { Authorization: "Bearer " + TOKEN },
});
if (!res.ok) throw new Error("usage HTTP " + res.status);

const data = await res.json();
console.log("Баланс USD:", data.balance_usd);
for (const m of data.by_model) console.log(m.model, "->", m.cost_usd);

#Алерт на остаток баланса

Простой скрипт: раз в час читает баланс через ro_… и предупреждает, если он ниже порога. Подключите отправку в Telegram-бота или почту — и 402 больше не застанет прод врасплох.

balance-alert.sh
#!/usr/bin/env bash
# Предупреждение, если баланс ниже порога
set -euo pipefail

RO_TOKEN="ro_your_readonly_token"
THRESHOLD=5   # порог в USD

BALANCE=$(curl -s "https://api.tkbk.io/v1/usage?period=total" \
  -H "Authorization: Bearer $RO_TOKEN" \
  | grep -o '"balance_usd":[0-9.]*' | cut -d: -f2)

if awk "BEGIN{ exit !($BALANCE < $THRESHOLD) }"; then
  echo "Внимание: баланс tkbk.io = $BALANCE USD (ниже $THRESHOLD)"
  # здесь отправьте уведомление, например в Telegram
fi
crontab
# каждый час в :05 проверять баланс
5 * * * * /opt/tkbk/balance-alert.sh >> /var/log/tkbk-balance.log 2>&1
✓
Готовый мониторинг
Тех же данных хватает для Grafana / дашборда: balance_usd, daily_used_usd и by_model[].cost_usd обновляются в реальном времени.
Коды ошибок

Как ловить и обрабатывать `402` и `429`.

Лимиты и квоты

Дневной и оконный лимиты, RPM.

Безопасность

Где хранить ro-токен и как ротировать ключи.

Не помогло?

Напишите в Telegram — поможем с настройкой и подберём тариф. Или вернитесь ко всем разделам документации.

@nukindВсе доки