> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Лимиты расходов Claude apps gateway

> Ограничьте расходы каждого разработчика через Claude apps gateway по дням, неделям или месяцам. Установите лимиты с помощью Admin API, и шлюз будет их соблюдать в реальном времени при каждом запросе.

Лимиты расходов ограничивают, сколько каждый разработчик может потратить через ваш [Claude apps gateway](/ru/claude-apps-gateway) в течение дня, недели или месяца. Когда разработчик превышает свой лимит, шлюз возвращает `429` при следующем запросе и блокирует его до сброса периода или пока администратор не повысит лимит. Используйте лимиты расходов, чтобы установить потолок расходов для каждого разработчика, группы или всей организации на общем учетном данном.

Claude apps gateway пересылает все вычисления через одно общее учетное данное вышестоящего провайдера, поэтому счет вашего провайдера относит все к этому учетному данному, а не к отдельным разработчикам. Без лимитов на разработчика один неконтролируемый флот агентов может потратить всю приверженность организации. Лимиты расходов — это представление шлюза на уровне разработчика и автоматический выключатель поверх этого общего счета.

<h2 id="set-a-cap">
  Установка лимита
</h2>

С настроенным блоком [`admin:`](/ru/claude-apps-gateway-config#admin) в `gateway.yaml`, gateway предоставляет Admin API по адресу `/v1/organizations/spend_limits` и соблюдает лимиты в реальном времени при каждом запросе вывода. Сами лимиты устанавливаются через этот API, а не в `gateway.yaml`; каждый запрос `POST /v1/organizations/spend_limits` создает или заменяет один лимит из `{scope, amount, period}`. API отражает форматы проводки публичного [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) Anthropic для лимитов расходов, поэтому HTTP-клиент, написанный для этого контракта, может нацеливаться на gateway, изменив его базовый URL.

Этот запрос устанавливает организационный лимит по умолчанию в размере \$500 в месяц для каждого разработчика:

```bash theme={null}
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"}'
```

Этот запрос добавляет более строгий лимит в размере \$100 в день для каждого члена группы `contractors`:

```bash theme={null}
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](/ru/claude-apps-gateway-config#managed) по имени; передайте его как `scope.rbac_group_id`. `organization` — это организационный лимит по умолчанию. Gateway принимает все три; публичный `POST` Anthropic сегодня поддерживает только пользователей. |
| `amount`     | Строка целого числа в центах USD или `null` | `null` означает неограниченно. `"0"` — это нулевой лимит, который блокирует каждый запрос.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `period`     | `daily`, `weekly`, `monthly`                | Область может содержать один лимит на период, и каждый применяется независимо: разработчик блокируется, если превышает любой из них.                                                                                                                                                                                                                                                                                                                                                         |

Лимит группы или организации — это лимит по умолчанию на одного пользователя, который наследует каждый член, а не общий пул. За период эффективный лимит разработчика разрешается в этом порядке: переопределение для конкретного пользователя, затем наиболее строгий из его групповых лимитов, затем организационный лимит по умолчанию, затем неограниченно. [`admin.group_limit_mode: max`](/ru/claude-apps-gateway-config#admin) переключает разрешение конфликта для нескольких групп на наименее строгий вместо этого.

<h3 id="authenticate-to-the-admin-api">
  Аутентификация в Admin API
</h3>

Отправьте одно из следующего:

* Заголовок `x-api-key`, соответствующий ключу в [`admin.write_keys`](/ru/claude-apps-gateway-config#admin) для полного доступа или `admin.read_keys` для доступа только для чтения `GET`. Каждый ключ имеет `id`, который появляется в журнале аудита как `admin-key:<id>`, поэтому дайте Terraform, CI и каждой автоматизации свой собственный.
* Токен bearer gateway, чей claim `groups` включает одну из [`admin.admin_groups`](/ru/claude-apps-gateway-config#admin). Это полный доступ и аудит как `oidc:<sub>`, поэтому предпочитайте это для администраторов-людей.

<h2 id="how-enforcement-works">
  Как работает соблюдение
</h2>

При каждом запросе `/v1/messages` gateway разрешает лимиты разработчика и расходы с начала периода в одном запросе Postgres. Если они превышают какой-либо лимит, запрос возвращает `429` с `error.type: billing_error` и заголовком `x-should-retry: false`. Сообщение — это `spend limit reached`, за которым следует ваш [`admin.blocked_message`](/ru/claude-apps-gateway-config#admin), если установлен.

`/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. Без этого ограниченный разработчик мог бы потоком передавать выходные данные и прерывать каждый запрос непосредственно перед концом, тратя без учета.

<h3 id="postgres-availability">
  Доступность Postgres
</h3>

Предварительная проверка запрашивает Postgres с двухсекундным тайм-аутом. Если хранилище недоступно или истекает время ожидания, соблюдение по умолчанию не срабатывает: запрос продолжается и gateway регистрирует предупреждение. Установите [`enforcement.fail_closed_on_error: true`](/ru/claude-apps-gateway-config#enforcement), чтобы вместо этого не срабатывать закрыто, что возвращает то же самое `429 billing_error` с сообщением `spend limit unavailable`. Отказ в открытом виде предотвращает превращение сбоя хранилища в сбой вывода; отказ в закрытом виде гарантирует отсутствие неучтенных расходов.

<h2 id="admin-api-reference">
  Справочник Admin API
</h2>

Конечные точки ниже обслуживаются в `/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=`.      |

Соглашения отражают Admin API Anthropic:

* `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 шлюза.

<h3 id="/effective">
  `/effective`
</h3>

`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` предыдущего ответа.                                         |

<Warning>
  `q=` и `user_ids[]=` находятся в строках запроса GET, поэтому любой фасадный прокси или балансировщик нагрузки захватывает их в своих журналах доступа. Если ваша политика логирования PII строгая, очистите эти параметры там.
</Warning>

<h3 id="/audit">
  `/audit`
</h3>

Возвращает журнал мутаций лимитов расходов: кто изменил какой лимит, снимки до/после и необязательную причину, самые новые первыми. `has_more` точен. Эта конечная точка следует локальным соглашениям Admin API, а не форме проводки первой стороны.

<h3 id="pagination">
  Разбиение на страницы
</h3>

Необработанный список разбивается на страницы по `after_id` и `before_id`, которые являются взаимоисключающими ID `spl_…`; результаты упорядочены по созданию и `has_more` отражает направление обхода. `/effective` разбивается на страницы по непрозрачному токену `next_page`, переданному обратно как `?page=`, с участниками, упорядоченными по возрастанию, поэтому страницы остаются стабильными во время записи расходов. `limit` — это 1–1000, по умолчанию 20, на обоих.

<h2 id="data-lifecycle">
  Жизненный цикл данных
</h2>

Gateway содержит четыре таблицы, связанные с расходами; почасовая очистка применяет окна удержания:

| Таблица            | Содержимое                                                                                                | Удержание                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `spend`            | Счетчики расходов с начала периода на одного участника в центах                                           | [`admin.spend_retention_months`](/ru/claude-apps-gateway-config#admin), по умолчанию 13                                 |
| `spend_limits`     | Настроенные лимиты                                                                                        | До удаления через API                                                                                                   |
| `admin_audit`      | Журнал мутаций                                                                                            | [`admin.audit_retention_days`](/ru/claude-apps-gateway-config#admin), по умолчанию 365                                  |
| `principal_emails` | Последний видимый адрес электронной почты каждого участника, отображаемое имя и группы IdP. Содержит PII. | [`admin.identity_retention_days`](/ru/claude-apps-gateway-config#admin) с момента последней активности, по умолчанию 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` и стареют в своих собственных окнах.

<h2 id="related">
  Связанное
</h2>

* [Конфигурация `admin` и `enforcement`](/ru/claude-apps-gateway-config#admin): включение Admin API и настройка удержания
* [Руководство по развертыванию](/ru/claude-apps-gateway-deploy#postgres): схема Postgres и рекомендации по резервному копированию