Usage API — расширение Guard для автоматического контроля собственного ключа. Оно показывает баланс, агрегаты и историю запросов Claude, Kimi, Composer и Grok, включая бесплатный подсчёт токенов там, где он поддержан. Это не организационный Admin API Anthropic и не даёт доступа к чужим ключам.
| Параметр | Правило |
|---|---|
starting_at | Начало окна RFC 3339; по умолчанию 30 дней до ending_at |
ending_at | Исключающая верхняя граница RFC 3339; по умолчанию начало завтрашнего дня UTC |
bucket_width | Только 1d |
curl -G https://api.guardrelay.ai/v1/usage \
-H "x-api-key: $GUARD_API_KEY" \
--data-urlencode "starting_at=2026-07-01T00:00:00Z" \
--data-urlencode "ending_at=2026-07-08T00:00:00Z" \
--data-urlencode "bucket_width=1d"{
"object": "usage_report",
"starting_at": "2026-07-01T00:00:00.000Z",
"ending_at": "2026-07-08T00:00:00.000Z",
"bucket_width": "1d",
"current_balance": {
"scope": "key_including_inflight_reservations",
"credit_usd": "100.00000000",
"used_usd": "3.42000000",
"remaining_usd": "96.58000000"
},
"retention": {
"detailed_days": 90,
"detailed_starting_at": "2026-04-09T12:00:00.000Z",
"daily_aggregates": "lifetime"
},
"tracking_started_at": "2026-07-01T08:30:00.000Z",
"data": [],
"totals": {
"requests": 18,
"successful_requests": 16,
"failed_requests": 1,
"cancelled_requests": 1,
"interrupted_requests": 0,
"input_tokens": 123456,
"output_tokens": 7890,
"cached_input_tokens": 20000,
"cache_creation_input_tokens": 1000,
"web_search_requests": 2,
"web_fetch_requests": 1,
"server_tool_error_count": 1,
"token_cost_usd": "0.42000000",
"server_tool_cost_usd": "0.02000000",
"total_cost_usd": "0.44000000"
},
"tracked_totals": {
"scope": "selected_inference_requests_since_tracking_started_at",
"requests": 18,
"successful_requests": 16,
"failed_requests": 1,
"cancelled_requests": 1,
"interrupted_requests": 0,
"input_tokens": 123456,
"output_tokens": 7890,
"cached_input_tokens": 20000,
"cache_creation_input_tokens": 1000,
"web_search_requests": 2,
"web_fetch_requests": 1,
"server_tool_error_count": 1,
"token_cost_usd": "0.42000000",
"server_tool_cost_usd": "0.02000000",
"total_cost_usd": "0.44000000"
},
"token_counting": {
"calls": 3,
"successful_calls": 2,
"failed_calls": 1,
"cancelled_calls": 0,
"interrupted_calls": 0,
"counted_input_tokens": 45678
},
"tracked_token_counting": {
"scope": "selected_token_estimates_since_tracking_started_at",
"calls": 4,
"successful_calls": 3,
"failed_calls": 1,
"cancelled_calls": 0,
"interrupted_calls": 0,
"counted_input_tokens": 60000
},
"by_model": []
}Пример сокращён: data и by_model намеренно оставлены пустыми. data, totals, tracked_totals и by_model содержат выбранные запросы генерации всех семейств, включая outcomes с нулевой стоимостью; бесплатный count_tokens отделён и не добавляется к их токенам или стоимости. token_counting показывает count-вызовы выбранного окна, tracked_token_counting — с tracking_started_at; обе операции остаются видны поштучно в /v1/usage/requests. tracking_started_at — нижняя граница покрытия и может быть null, пока не записано первое событие; после свёртки самой ранней детализации он округляется вниз до начала UTC-дня первого агрегата. Поле daily_aggregates: "lifetime" означает, что свёрнутые отслеживаемые дневные агрегаты не удаляются; история до запуска трекинга не восстанавливается. Все поля *_usd — строки с 8 знаками после точки; timestamps возвращаются в RFC 3339 UTC (Z). starting_at и ending_at должны быть границами суток UTC; максимальное окно — 366 дней.
| Параметр | Правило |
|---|---|
starting_at / ending_at | RFC 3339 с timezone; по умолчанию последние 90 дней |
limit | 1–100, по умолчанию 50 |
cursor | Подписанный opaque-токен из next_cursor; передавайте без изменений. Он фиксирует окно и фильтры исходной страницы |
status | Точный статус из списка ниже |
outcome | Грубая группа: success, failed, cancelled или interrupted; вместе со status работает как AND |
operation | messages или count_tokens |
curl -G https://api.guardrelay.ai/v1/usage/requests \
-H "x-api-key: $GUARD_API_KEY" \
--data-urlencode "status=server_tool_error" \
--data-urlencode "operation=messages" \
--data-urlencode "limit=50"{
"object": "list",
"data": [
{
"request_id": "req_0123456789abcdef0123456789abcdef",
"created_at": "2026-09-09T11:20:31.120Z",
"completed_at": "2026-09-09T11:20:32.960Z",
"operation": "messages",
"status": "server_tool_error",
"retryable": false,
"http_status": 200,
"latency_ms": 1840,
"model": "claude-opus-5",
"stream": false,
"usage": {
"input_tokens": 840,
"output_tokens": 90,
"cached_input_tokens": 0,
"cache_creation_input_tokens": 0
},
"server_tools": {
"web_search_requests": 0,
"web_fetch_requests": 1,
"error_count": 1
},
"cost": {
"token_cost_usd": "0.00483750",
"server_tool_cost_usd": "0.00000000",
"total_cost_usd": "0.00483750"
},
"error": {
"code": "server_tool_error",
"message": "Серверный инструмент завершился ошибкой. Проверьте его параметры или повторите запрос.",
"action": "Исправьте указанные параметры и повторите запрос."
},
"family": "claude",
"server_prompt_applied": false,
"discount_percent": 25
}
],
"has_more": true,
"next_cursor": "<opaque-signed-cursor>",
"retention": {
"detailed_days": 90,
"detailed_starting_at": "2026-06-11T12:00:00.000Z",
"daily_aggregates": "lifetime"
}
}pending,success,client_error,rate_limited,policy_refusal.upstream_error,stream_error,server_tool_error,internal_error.cancelled— клиент отменил запрос;interrupted— запрос прерван рестартом сервиса.retryableподсказывает, имеет ли смысл автоматически повторить вызов.- Бесплатный
count_tokensтакже появляется в журнале, но с нулевой стоимостью.
- Детальные logical events хранятся 90 дней; текущая нижняя граница детализации указана в
retention.detailed_starting_at. - Более старые отслеживаемые события сворачиваются в дневные агрегаты, которые не удаляются. Запросы до
tracking_started_atне backfill'ятся. - Эти endpoint'ы не возвращают prompts, ответы, URL/поисковые запросы, содержимое документов, tool arguments, IP, User-Agent и raw errors.
- Не раскрываются внутренние детали обработки запросов, аккаунты и сетевые данные. Ошибки нормализованы в безопасные
code+message. - Пагинация идёт от новых событий к старым: если
has_more=true, передайтеnext_cursorбез изменений как следующийcursor. Окно и фильтры можно не повторять — они восстановятся из cursor; если повторяете, значения должны совпасть точно. Изменённый, чужой или malformed cursor получает одинаковый400 Invalid cursor.
Фильтр family принимает all, claude, kimi, composer и grok. Без параметра выбираются все семейства.
Разбор Kimi-расхода, отдельные ставки и формула резерва вынесены на страницу Kimi · Цены, reserve и usage.
Расход Kimi лежит в том же отчёте, что и остальной: ключ и баланс общие. Его отбирают два действующих фильтра, family и endpoint; они работают вместе как И.
| Фильтр | Что принимает |
|---|---|
family | all, claude, kimi, composer, grok; по умолчанию all |
mode | Удалён: любое значение возвращает 410 product_modes_removed; уберите параметр |
endpoint | chat_completions, messages, responses, search, fetch, token_estimate или all |
curl -G https://api.guardrelay.ai/v1/usage \
-H "Authorization: Bearer $GUARD_API_KEY" \
--data-urlencode "family=kimi" \
--data-urlencode "bucket_width=1d"curl -G https://api.guardrelay.ai/v1/usage/requests \
-H "Authorization: Bearer $GUARD_API_KEY" \
--data-urlencode "family=kimi" \
--data-urlencode "endpoint=chat_completions" \
--data-urlencode "limit=50"