API статистики и расходов

API использования и биллинга TeamoRouter позволяют получить расход токенов и стоимость отдельных запросов к моделям, агрегированные данные за период и текущий баланс аккаунта.

Обзор API

Начало работы

Base URL

Используйте API Base URL, показанный в консоли TeamoRouter. В примерах ниже он обозначен как $TEAMO_BASE_URL:

export TEAMO_BASE_URL="https://teamorouter.com"

Аутентификация

Передавайте API-ключ TeamoRouter в заголовке Authorization каждого запроса:

Authorization: Bearer sk-teamo-xxx

Храните ключ в безопасности. Не включайте его во фронтенд-код, публичные репозитории и логи. Все ключи и ID в примерах вымышлены.

Расход токенов и стоимость запроса

По ID запроса получите расход токенов и итоговую стоимость одного вызова модели.

GET /v1/billing/requests/{request_id}

Параметры пути

Пример запроса

curl "$TEAMO_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

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

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": 1784081234,
  "model": "gpt-5.4",
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "cached_write_tokens": 800,
    "cached_read_tokens": 200,
    "total_tokens": 2500
  },
  "amount": {
    "value": "0.012680",
    "currency": "USD"
  }
}

Поля токенов

Категории токенов, которые неприменимы или не предоставлены вышестоящим сервисом, возвращают 0.

Получить списания за период

Итоги списаний по аутентифицированному API-ключу за период. Базовый ответ содержит только агрегированные данные, без отдельных записей о запросах.

GET /v1/billing/costs

Параметры запроса

Период не должен превышать 90 дней. Более длинные периоды возвращают 400 invalid_request.

Пример запроса

curl "$TEAMO_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

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

{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "total_amount": {
    "value": "1.280000",
    "currency": "USD"
  },
  "requests": 86
}

Получить расход токенов за период

Агрегированный расход токенов по аутентифицированному API-ключу за период.

GET /v1/usage

Параметры запроса

Период не должен превышать 90 дней. Более длинные периоды возвращают 400 invalid_request.

Пример запроса

curl "$TEAMO_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

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

{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "usage": {
    "input_tokens": 120000,
    "output_tokens": 30000,
    "cached_write_tokens": 10000,
    "cached_read_tokens": 80000,
    "total_tokens": 240000
  },
  "requests": 86
}

Получить баланс аккаунта

Доступный баланс аккаунта, связанного с текущим API-ключом.

GET /v1/billing/balance

Этот эндпоинт не принимает параметров запроса. Аккаунт определяется по API-ключу.

Пример запроса

curl "$TEAMO_BASE_URL/v1/billing/balance" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

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

{
  "balance": {
    "value": "85.320000",
    "currency": "USD"
  }
}

Обработка ошибок

При сбое вызова тело ответа содержит стабильный код ошибки и сообщение, помогающее диагностировать проблему.

{
  "error": {
    "code": "invalid_request",
    "message": "end_time must be greater than start_time"
  }
}

Частые коды ошибок

Рекомендации

• При сверке использования и списаний используйте одинаковые start_time и end_time, чтобы оба запроса охватывали один и тот же период.
• Цены могут меняться. Для прошлых списаний используйте amount из исторических записей, а не пересчитывайте их по текущему прайсу.
• Настройте разумные таймауты и повторы. Для ответов 429 и 5xx используйте экспоненциальную задержку.