API лимитов расходов

API лимитов расходов позволяет устанавливать лимит расходов для каждого участника Claude Enterprise, просматривать, откуда наследуется лимит расходов каждого участника, а также рассматривать запросы участников на повышение лимита и принимать по ним решения.

Для отчётности по использованию и затратам в разрезе пользователей и временных интервалов см. API аналитики.



Обзор

API предоставляет восемь конечных точек для двух ресурсов:

Используйте конечные точки лимитов расходов, чтобы ответить на вопрос «какой лимит расходов применяется к каждому участнику, откуда он берётся и насколько участник близок к нему?», а также чтобы установить индивидуальное переопределение для пользователя. Используйте конечные точки запросов на повышение лимита расходов для обработки очереди запросов, отправленных участниками.



Предварительные требования

• Ваша организация должна быть на тарифном плане Claude Enterprise.
• Для вашей организации должны быть включены кредиты использования. Основной владелец может включить их в настройках биллинга claude.ai.



Быстрый старт

Получите список действующих месячных лимитов расходов и расходов с начала периода для каждого участника:

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Ключевые понятия



Иерархия лимитов расходов

К расходам каждого участника применяется действующий лимит расходов, определяемый на основе иерархии уровней области действия. Если у участника нет индивидуального переопределения, он наследует лимит расходов, настроенный для его группы (если ваша организация использует групповые лимиты), его уровня места или значение по умолчанию для всей организации. Групповой лимит расходов — это значение по умолчанию для каждого участника: каждый участник, наследующий его, ограничивается по собственным расходам, а не по общему бюджету группы.

Запрос GET /v1/organizations/spend_limits/effective возвращает каждого текущего участника с его определённым действующим лимитом расходов, источником, из которого этот лимит был определён (source), и его расходами с начала периода. Установка индивидуального переопределения с помощью POST /v1/organizations/spend_limits закрепляет за участником конкретный лимит расходов независимо от того, что он унаследовал бы в противном случае. Удаление переопределения возвращает участника к унаследованному лимиту расходов (или оставляет его без ограничений, если такового не существует).

Поле source в строке каждого участника указывает, с какого уровня был определён его лимит расходов: user (индивидуальное переопределение), seat_tier, rbac_group или organization. Рассматривайте типы областей действия как открытое множество; при неизвестных значениях переходите к обработке по умолчанию, а не завершайтесь с ошибкой.



Период

period — это повторяющееся окно, в рамках которого применяется лимит расходов и обнуляются расходы. Лимит расходов идентифицируется парой (scope, period). В настоящее время monthly — единственный поддерживаемый период; месячные расходы обнуляются в 00



Суммы и валюта

Все денежные значения представлены строками в минорных единицах валюты биллинга организации (центах для USD). Например, "50000" соответствует 500,00 USD. Разбирайте значение как десятичное число и делите на 100 для отображения в долларах; избегайте двоичных чисел с плавающей запятой для больших значений.

Поле amount допускает значение null. В строке действующего лимита участника null означает без ограничений (лимит расходов отсутствует), а "0" означает, что участник не может использовать Claude сверх использования, включённого в его тарифный план. В строке настроенного лимита расходов (возвращаемой GET /v1/organizations/spend_limits/{id}) null означает лишь то, что числовой лимит расходов не установлен; чтобы отличить отсутствие ограничений от режима «только включённое использование», прочитайте строку действующего лимита участника.

period_to_date_spend — это расходы участника, накопленные с начала текущего period, в том же формате минорных единиц; значение может содержать дробную часть (например, "41280.125"). Оно может отображаться как "0", если данные о расходах временно недоступны; рассматривайте его как информационное, а не транзакционное.



Жизненный цикл запроса на повышение

Запрос на повышение лимита расходов создаётся, когда участник нажимает Request more usage в claude.ai. Запросы не создаются через этот API. Поле status запроса принимает одно из следующих значений:

Оба статуса approved и denied являются конечными. У участника может быть не более одного запроса со статусом pending одновременно.

Одобрение с помощью POST /v1/organizations/spend_limit_increase_requests/{id}/approve записывает ту же строку индивидуального лимита расходов, что и POST /v1/organizations/spend_limits. Прямая установка лимита расходов не переводит ожидающий запрос в другой статус; используйте конечную точку одобрения, чтобы разрешить запрос.

По умолчанию Anthropic отправляет участнику электронное письмо, когда его запрос одобрен или отклонён. Передайте suppress_notification: true при одобрении или отклонении, чтобы подавить это письмо (например, если ваша собственная система уведомляет участника).



Ограничение скорости

Все восемь конечных точек используют общий лимит 60 запросов в минуту на организацию. Запросы сверх лимита возвращают 429 Too Many Requests.



Пагинация

GET /v1/organizations/spend_limits/effective и GET /v1/organizations/spend_limit_increase_requests используют пагинацию с непрозрачным курсором. Первый запрос возвращает до limit строк плюс курсор next_page; передайте этот курсор без изменений в параметре page в следующем запросе и повторяйте, пока next_page не станет null.

Не изменяйте параметры запроса в середине последовательности. Курсоры привязаны к фильтрам, с которыми они были выданы. Если вы измените user_ids[], period[], status[] или actor_ids[] и передадите старый курсор, вы получите ошибку 400 с сообщением «cursor does not match current query parameters». Вместо этого начните новую последовательность с первой страницы.



Сериализация списочных параметров

Списочные параметры используют нотацию с квадратными скобками: повторяйте имя параметра с [] для каждого значения.

user_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPq



Ответы с ошибками

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



Лимиты расходов



Получение списка действующих лимитов расходов участников

GET /v1/organizations/spend_limits/effective возвращает по одной строке на каждого текущего участника, отражая действующий лимит расходов каждого участника, его source в иерархии областей действия и его period_to_date_spend. Требуется область действия read:spend_limits.

Полные сведения о параметрах и схемы ответов см. в разделе Список действующих лимитов расходов справочника API.

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "[email protected]",
        "deleted": false
      },
      "amount": "50000",
      "currency": "USD",
      "period": "monthly",
      "source": { "type": "seat_tier", "seat_tier": "enterprise_standard" },
      "spend_limit_id": "spl_01XyZaBcDeFgHiJkLmNoPq",
      "period_to_date_spend": "31402.5"
    }
  ],
  "next_page": "page_..."
}



Получение отдельного лимита расходов

GET /v1/organizations/spend_limits/{spend_limit_id} возвращает один настроенный лимит расходов по идентификатору. Используйте его для проверки строки, на которую ссылалось поле spend_limit_id. Требуется область действия read:spend_limits.

Полные сведения о параметрах и схемы ответов см. в разделе Получение лимита расходов справочника API.

curl "https://api.anthropic.com/v1/organizations/spend_limits/spl_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Установка индивидуального переопределения

POST /v1/organizations/spend_limits устанавливает индивидуальное переопределение лимита расходов для пользователя. Это операция upsert с ключом (scope, period): установка лимита для пользователя и периода, для которых лимит уже существует, перезаписывает его на месте. Эта конечная точка принимает только scope.type: "user"; значения по умолчанию на уровне места, группы и организации настраиваются в настройках claude.ai. Требуется область действия write:spend_limits.

Полные сведения о параметрах и схемы ответов см. в разделе Создание лимита расходов справочника API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limits" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"scope": {"type": "user", "user_id": "user_01AbCdEfGh"}, "amount": "75000"}'

{
  "type": "spend_limit",
  "id": "spl_01RsTuVwXyZaBcDeFgHiJk",
  "created_at": "2026-05-11T10:02:44Z",
  "updated_at": "2026-05-11T10:02:44Z",
  "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
  "amount": "75000",
  "currency": "USD",
  "period": "monthly"
}



Удаление индивидуального переопределения

DELETE /v1/organizations/spend_limits/{spend_limit_id} удаляет индивидуальное переопределение, после чего участник возвращается к любому унаследованному значению по умолчанию на уровне места, группы или организации. Строки уровня места, группы и организации не могут быть удалены через эту конечную точку. Требуется область действия write:spend_limits.

Полные сведения о параметрах и схемы ответов см. в разделе Удаление лимита расходов справочника API.

curl --request DELETE "https://api.anthropic.com/v1/organizations/spend_limits/spl_01RsTuVwXyZaBcDeFgHiJk" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Запросы на повышение лимита расходов



Получение списка запросов на повышение

GET /v1/organizations/spend_limit_increase_requests возвращает список запросов, начиная с самых последних. Фильтруйте по status[] (pending, approved, denied) и actor_ids[]. Список исключает запросы, автор которых больше не является участником организации. Требуется область действия read:spend_limits.

Полные сведения о параметрах и схемы ответов см. в разделе Список запросов на повышение лимита расходов справочника API.

curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=50" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Каждый ожидающий запрос содержит актуальный spend_summary, показывающий текущий действующий лимит расходов автора запроса и его расходы с начала периода — этого достаточно для принятия решения без отдельного запроса.



Получение отдельного запроса на повышение

GET /v1/organizations/spend_limit_increase_requests/{id} возвращает один запрос по идентификатору. Требуется область действия read:spend_limits.

Полные сведения о параметрах и схемы ответов см. в разделе Получение запроса на повышение лимита расходов справочника API.

curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Одобрение запроса на повышение

POST /v1/organizations/spend_limit_increase_requests/{id}/approve одобряет ожидающий запрос: записывает индивидуальный лимит расходов с указанным администратором значением amount для автора запроса и переводит запрос в статус approved. Запрос не содержит запрашиваемой суммы; вы указываете новый лимит расходов при одобрении. Требуется область действия write:spend_limits.

Полные сведения о параметрах и схемы ответов см. в разделе Одобрение запроса на повышение лимита расходов справочника API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/approve" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"amount": "75000", "suppress_notification": true}'



Отклонение запроса на повышение

POST /v1/organizations/spend_limit_increase_requests/{id}/deny отклоняет ожидающий запрос. Идемпотентно для статуса denied: отклонение уже отклонённого запроса возвращает 200 с существующим ресурсом. Конечная точка отвергает попытку отклонить уже одобренный запрос, чтобы автоматизация могла отличить повторную попытку от конфликтующего решения. Требуется область действия write:spend_limits.

Полные сведения о параметрах и схемы ответов см. в разделе Отклонение запроса на повышение лимита расходов справочника API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/deny" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"suppress_notification": true}'



Часто задаваемые вопросы



Разрешает ли прямая установка лимита расходов ожидающий запрос участника на повышение?

Нет. POST /v1/organizations/spend_limits записывает переопределение, но оставляет ожидающий запрос без изменений. Используйте POST /v1/organizations/spend_limit_increase_requests/{id}/approve, чтобы разрешить запрос и записать переопределение одним вызовом.



Что происходит при удалении индивидуального переопределения?

Участник возвращается к тому, что он унаследовал бы из иерархии: значению по умолчанию его группы, уровня места или организации. Если значение по умолчанию не существует ни на одном уровне, участник не ограничен.



Можно ли установить значение по умолчанию для уровня места или всей организации через этот API?

Нет. Через этот API можно записывать только индивидуальные переопределения для пользователей. Значения по умолчанию на уровне места, группы и организации настраиваются в настройках организации claude.ai.



Почему period_to_date_spend иногда отображается как "0" для активного участника?

Данные о расходах могут быть временно недоступны, и в этом случае поле отображается как "0" вместо возврата ошибки. Рассматривайте его как информационное.



См. также