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"



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



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

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

Запрос 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}'



Примеры рабочих процессов

Эти рабочие процессы сочетают API лимитов расходов с конечными точками затрат API аналитики. Конечные точки затрат API аналитики предназначены для отчётности по расходам всей организации за диапазон дат. GET /spend_limits/effective возвращает лимит, который в настоящее время применяется к каждому участнику. Начните обход с API аналитики, чтобы определить, каких участников следует рассмотреть, затем прочитайте их текущие лимиты с помощью /effective.

Конечные точки лимитов расходов требуют областей действия spend_limits, а конечные точки затрат API аналитики требуют read:analytics; см. API аналитики, чтобы узнать, как предоставить доступ. Все денежные значения в обоих API — десятичные строки в минорных единицах (центах). Оба API используют пагинацию с непрозрачным курсором. Установите явный limit и проходите по страницам через next_page, пока он не станет null, чтобы охватить всю организацию.



Автоматизация процесса рассмотрения запросов на повышение

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

1. Получите список ожидающих запросов:

   cURL

   

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

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

2. Примените вашу политику. Например, автоматически одобряйте, когда текущий amount участника ниже порогового значения, и направляйте более крупные лимиты на ручное рассмотрение.

3. Разрешите каждый запрос. Для одобрения укажите новый лимит:

   cURL

   

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

   Для отклонения выполните POST к .../{id}/deny. Передайте suppress_notification: true, если ваша собственная система уведомляет автора запроса.



Выявление участников, близких к своему лимиту расходов

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

1. Получите расходы каждого участника с начала месяца из API аналитики (по одной строке на участника, по умолчанию сначала наибольшие расходы):

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-01T00:00:00Z&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY"

   Каждая строка содержит actor.user_id, actor.email и amount (расходы участника в центах). Проходите по страницам через next_page, чтобы охватить всю организацию.

2. Для участников с наибольшими расходами (или всех, кто превысил долларовый порог) получите действующие лимиты пакетами:

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01Ab...&user_ids[]=user_01Cd...&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

   Каждая строка возвращает лимит в поле amount (null = без ограничений, "0" = только включённое использование) вместе с period_to_date_spend.

3. Для каждого участника с положительным лимитом вычислите period_to_date_spend / amount и отметьте тех, кто достиг вашего порога или превысил его (например, 80 процентов). Лимит "0" рассматривайте как уже достигнутый. Серверного фильтра для этого соотношения не существует.

4. Примите меры в отношении отмеченных участников: повысьте лимит с помощью POST /v1/organizations/spend_limits, одобрите ожидающий запрос на повышение, если он существует, или свяжитесь с участником.



Поиск участников с быстро меняющимся использованием

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

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

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-09T00:00:00Z&ending_at=2026-06-23T00:00:00Z&bucket_width=1d&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY"

   При установленном bucket_width каждый участник занимает по одной строке на день с использованием; проходите по страницам через next_page, чтобы собрать полный ряд данных для каждого участника.

2. Сгруппируйте строки по actor.user_id. Для каждого участника просуммируйте последние семь дней и предыдущие семь дней. Отметьте участников, чья последняя неделя превышает предыдущую в выбранное вами число раз (например, в три раза). Затраты за последние дни являются предварительными и могут быть пересмотрены в сторону увеличения; для воспроизводимых сравнений установите ending_at на момент не позднее ранее возвращённого data_refreshed_at (см. Доступность и актуальность данных).

3. Примите меры в отношении отмеченных участников: скорректируйте лимит с помощью POST /v1/organizations/spend_limits или свяжитесь с участником.



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



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

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



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

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



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

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



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

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



См. также