Лимиты расходов ограничивают, сколько каждый разработчик может потратить через ваш Claude apps gateway в течение дня, недели или месяца. Когда разработчик превышает свой лимит, шлюз возвращает 429 при следующем запросе и блокирует его до сброса периода или пока администратор не повысит лимит. Используйте лимиты расходов, чтобы установить потолок расходов для каждого разработчика, группы или всей организации на общем учетном данном.
Claude apps gateway пересылает все вычисления через одно общее учетное данное вышестоящего провайдера, поэтому счет вашего провайдера относит все к этому учетному данному, а не к отдельным разработчикам. Без лимитов на разработчика один неконтролируемый флот агентов может потратить всю приверженность организации. Лимиты расходов — это представление шлюза на уровне разработчика и автоматический выключатель поверх этого общего счета.
Установка лимита
С настроенным блоком admin: в gateway.yaml, gateway предоставляет Admin API по адресу /v1/organizations/spend_limits и соблюдает лимиты в реальном времени при каждом запросе вывода. Сами лимиты устанавливаются через этот API, а не в gateway.yaml; каждый запрос POST /v1/organizations/spend_limits создает или заменяет один лимит из {scope, amount, period}. API отражает форматы проводки публичного Admin API Anthropic для лимитов расходов, поэтому HTTP-клиент, написанный для этого контракта, может нацеливаться на gateway, изменив его базовый URL.
Этот запрос устанавливает организационный лимит по умолчанию в размере $500 в месяц для каждого разработчика:
curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
-H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
-H "Content-Type: application/json" \
-d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'
contractors:
curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
-H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
-H "Content-Type: application/json" \
-d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'
| Поле | Значения | Описание |
|---|
scope.type | user, rbac_group, organization | user нацеливается на одного разработчика по его OpenID Connect (OIDC) sub, стабильному ID пользователя, который назначает ваш поставщик идентификации; передайте его как scope.user_id. rbac_group нацеливается на группу IdP по имени; передайте его как scope.rbac_group_id. organization — это организационный лимит по умолчанию. Gateway принимает все три; публичный POST Anthropic сегодня поддерживает только пользователей. |
amount | Строка целого числа в центах USD или null | null означает неограниченно. "0" — это нулевой лимит, который блокирует каждый запрос. |
period | daily, weekly, monthly | Область может содержать один лимит на период, и каждый применяется независимо: разработчик блокируется, если превышает любой из них. |
admin.group_limit_mode: max переключает разрешение конфликта для нескольких групп на наименее строгий вместо этого.
Аутентификация в Admin API
Отправьте одно из следующего:
- Заголовок
x-api-key, соответствующий ключу в admin.write_keys для полного доступа или admin.read_keys для доступа только для чтения GET. Каждый ключ имеет id, который появляется в журнале аудита как admin-key:<id>, поэтому дайте Terraform, CI и каждой автоматизации свой собственный.
- Токен bearer gateway, чей claim
groups включает одну из admin.admin_groups. Это полный доступ и аудит как oidc:<sub>, поэтому предпочитайте это для администраторов-людей.
Как работает соблюдение
При каждом запросе /v1/messages gateway разрешает лимиты разработчика и расходы с начала периода в одном запросе Postgres. Если они превышают какой-либо лимит, запрос возвращает 429 с error.type: billing_error и заголовком x-should-retry: false. Сообщение — это spend limit reached, за которым следует ваш admin.blocked_message, если установлен.
/v1/messages/count_tokens исключен. Подсчет токенов бесплатен, поэтому он работает независимо от состояния лимита.
После каждого ответа счетчик использования читает количество токенов из ответа по мере его потоковой передачи клиенту, оценивает их по цене USD по прайс-листу и увеличивает счетчики Postgres для всех трех периодических корзин. Счетчик — это один читатель потока, поэтому байты клиента не затрагиваются, и сбой измерения не нарушает ответ.
Лимиты расходов оценивают расходы на основе количества токенов по цене USD по прайс-листу; они являются автоматическим выключателем, а не счетом. Для авторитетного выставления счетов согласуйте с собственной отчетностью об использовании вашего провайдера, такой как Anthropic Usage & Cost Admin API, журналы вызовов на Bedrock или Cloud Monitoring на Google Cloud.
Ценообразование использует ту же таблицу, которую использует Claude Code CLI для собственного отображения стоимости, с той же канонизацией ID модели в формах Anthropic, Bedrock (us.anthropic.…-v1:0), Agent Platform (claude-…@date) и Foundry ID. ID модели, который таблица не может найти, такой как имя развертывания Foundry или ARN профиля вывода, оценивается по уровню неизвестной модели по умолчанию в размере $5/$25 за миллион входных/выходных токенов, а не нулю, поэтому неузнанный ID не может обойти лимит, оставаясь неизмеренным. Gateway предупреждает при загрузке и один раз за ID во время выполнения, когда модель оценивается через резервный вариант.
Прерывания клиента также учитываются. Upstream сообщает выходные токены только в терминальном кадре потока, поэтому прерванный поток их не содержит. Счетчик сохраняет консервативную оценку пола из размера потокового контента, примерно четыре символа на токен, и учитывает его, когда и только когда отсутствует терминальный кадр использования. Полный поток всегда учитывает количество, сообщаемое upstream. Без этого ограниченный разработчик мог бы потоком передавать выходные данные и прерывать каждый запрос непосредственно перед концом, тратя без учета.
Доступность Postgres
Предварительная проверка запрашивает Postgres с двухсекундным тайм-аутом. Если хранилище недоступно или истекает время ожидания, соблюдение по умолчанию не срабатывает: запрос продолжается и gateway регистрирует предупреждение. Установите enforcement.fail_closed_on_error: true, чтобы вместо этого не срабатывать закрыто, что возвращает то же самое 429 billing_error с сообщением spend limit unavailable. Отказ в открытом виде предотвращает превращение сбоя хранилища в сбой вывода; отказ в закрытом виде гарантирует отсутствие неучтенных расходов.
Справочник Admin API
Конечные точки ниже обслуживаются в /v1/organizations/spend_limits.
| Метод и путь | Описание |
|---|
GET /v1/organizations/spend_limits | Список настроенных лимитов. Запрос: ?limit=&after_id=&before_id=. |
POST /v1/organizations/spend_limits | Создать или заменить лимит для {scope, period}. |
GET /v1/organizations/spend_limits/{id} | Получить один лимит по его ID с префиксом spl_. |
DELETE /v1/organizations/spend_limits/{id} | Удалить один лимит. Возвращает {type: "spend_limit_deleted", id}. |
GET /v1/organizations/spend_limits/effective | Разрешенный лимит и расходы с начала периода на одного участника за период. |
GET /v1/organizations/spend_limits/audit | Журнал мутаций администратора, самые новые первыми. Запрос: ?limit=. |
type на каждом объекте- ID с префиксом
spl_
- Суммы как строки целых чисел в центах USD;
POST отклоняет любую другую currency с 400
- Конверт ошибки
{type: "error", error: {type, message}, request_id}
- Заголовок ответа
request-id при каждом ответе администратора, успехе или ошибке, соответствующий request_id тела
Каждая мутация записывает строку до/после в admin_audit в той же транзакции, отнесенную к admin-key:<id> или oidc:<sub>.
Шлюз обслуживает конечные точки лимитов расходов только. Другие поверхности Admin API, такие как очередь spend_limit_increase_requests, не являются частью Admin API шлюза.
/effective
GET /v1/organizations/spend_limits/effective возвращает схему SpendSummary Anthropic: каждая строка — это участник за период с разрешенным лимитом, расходами с начала периода и объектом actor. Различия, специфичные для gateway:
user_id — это OIDC sub.actor.name и actor.email_address — это null до первого запроса вывода участника через gateway. Gateway не имеет каталога пользователей; он записывает последние видимые значения из JWT сеанса каждого пользователя.- Каждая строка также содержит массив
groups, последние видимые группы IdP участника. Это расширение gateway, поэтому пользовательский интерфейс администратора может показать каждый уровень лимита, который применяется; клиенты, совместимые с Anthropic, игнорируют это.
- Без фильтра
user_ids[] он перечисляет участников с записанными расходами, потому что gateway не может перечислить всех членов организации.
Лимиты на основе групп разрешаются против этих последних видимых групп с тем же разрешением конфликта group_limit_mode, которое использует соблюдение, поэтому средство просмотра показывает применяемый лимит.
| Параметр запроса | Описание |
|---|
user_ids[] | Повторяемый. Фильтр для конкретных участников по OIDC sub. |
period[] | Повторяемый. Фильтр для строк daily, weekly или monthly. |
sort | spend_desc перечисляет крупнейших потребителей первыми. Требует ровно один period[]. |
q | Фильтр подстроки без учета регистра по OIDC sub, последнему видимому адресу электронной почты и последнему видимому отображаемому имени. |
limit / page | Размер страницы (1–1000, по умолчанию 20) и непрозрачный курсор из next_page предыдущего ответа. |
q= и user_ids[]= находятся в строках запроса GET, поэтому любой фасадный прокси или балансировщик нагрузки захватывает их в своих журналах доступа. Если ваша политика логирования PII строгая, очистите эти параметры там.
/audit
Возвращает журнал мутаций лимитов расходов: кто изменил какой лимит, снимки до/после и необязательную причину, самые новые первыми. has_more точен. Эта конечная точка следует локальным соглашениям Admin API, а не форме проводки первой стороны.
Необработанный список разбивается на страницы по after_id и before_id, которые являются взаимоисключающими ID spl_…; результаты упорядочены по созданию и has_more отражает направление обхода. /effective разбивается на страницы по непрозрачному токену next_page, переданному обратно как ?page=, с участниками, упорядоченными по возрастанию, поэтому страницы остаются стабильными во время записи расходов. limit — это 1–1000, по умолчанию 20, на обоих.
Жизненный цикл данных
Gateway содержит четыре таблицы, связанные с расходами; почасовая очистка применяет окна удержания:
| Таблица | Содержимое | Удержание |
|---|
spend | Счетчики расходов с начала периода на одного участника в центах | admin.spend_retention_months, по умолчанию 13 |
spend_limits | Настроенные лимиты | До удаления через API |
admin_audit | Журнал мутаций | admin.audit_retention_days, по умолчанию 365 |
principal_emails | Последний видимый адрес электронной почты каждого участника, отображаемое имя и группы IdP. Содержит PII. | admin.identity_retention_days с момента последней активности, по умолчанию 90 |
identity_retention_days намеренно короче, чем spend_retention_months: деподготовленная идентификация перестает обновляться и стареет, в то время как ее анонимные счетчики расходов остаются для отчетности год за годом.
Когда разработчик уходит, удалите любой лимит для конкретного пользователя через DELETE /v1/organizations/spend_limits/{id}; его расходы и строки идентификации стареют в окнах удержания выше. Чтобы стереть одного человека немедленно, для offboarding или запроса доступа субъекта данных (DSAR), запустите DELETE FROM principal_emails WHERE principal = '<sub>' непосредственно против базы данных gateway. Это удаляет единственную таблицу, содержащую их адрес электронной почты, имя и группы. Строки spend и admin_audit ссылаются только на псевдонимный OIDC sub и стареют в своих собственных окнах.
