Spend Limits API

Spend Limits API позволяет вам устанавливать «spend limit» (лимит расходов) для каждого участника Claude Enterprise, видеть, откуда наследуется лимит расходов каждого участника, а также просматривать запросы участников на повышение лимита и принимать по ним решения.

Для отчётности об использовании и затратах по отдельным пользователям и по временным интервалам см. Analytics APIs.

Обзор

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

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

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

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

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

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

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

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

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

К расходам каждого участника применяется действующий лимит расходов (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:00 UTC первого числа каждого календарного месяца. Рассматривайте period как открытое множество.

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

Все денежные значения представлены строками в минимальных единицах валюты биллинга организации (центах для 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", если данные о расходах временно недоступны; рассматривайте его как информационное, а не транзакционное.

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

Запрос на повышение лимита расходов (spend limit increase request) создаётся, когда участник нажимает 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 при одобрении или отклонении, чтобы подавить это письмо (например, если ваша собственная система уведомляет участника).

Версионирование

Отправляйте заголовок anthropic-version в каждом запросе; доступные версии см. в разделе Версии API.

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

Все восемь конечных точек используют единое «rate limit» (ограничение скорости) на организацию — 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" \
  --header "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "jane@example.com",
        "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" \
  --header "anthropic-version: 2023-06-01"

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

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" \
  --header "anthropic-version: 2023-06-01" \
  --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" \
  --header "anthropic-version: 2023-06-01"

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

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

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

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

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

Каждый ожидающий запрос содержит актуальный 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" \
  --header "anthropic-version: 2023-06-01"

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

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" \
  --header "anthropic-version: 2023-06-01" \
  --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" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"suppress_notification": true}'

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

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

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

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

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

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

   cURL

   

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

   Каждый запрос содержит 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" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"amount": "75000", "suppress_notification": true}'

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

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

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

1. Получите расходы каждого участника с начала месяца из Analytics 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" \
     --header "anthropic-version: 2023-06-01"

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

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

   cURL

   

   curl --globoff "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" \
     --header "anthropic-version: 2023-06-01"

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

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

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

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

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

1. Получите ежедневные затраты по каждому участнику за последние две недели из Analytics 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" \
     --header "anthropic-version: 2023-06-01"

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

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

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

Временное повышение лимита расходов участника во время инцидента

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

1. Прочитайте текущее ограничение участника и запишите его для отката:

   cURL

   

   curl --globoff "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01AbCdEfGh&period[]=monthly" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

2. Повысьте ограничение:

   cURL

   

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

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

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/rbac_groups/rbac_group_01UvWxYzAbCdEfGhIjKlMn/members" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"user_id": "user_01AbCdEfGh"}'

   Конечные точки для работы с группами см. в разделе Управление пользователями.

4. Когда ваша система управления инцидентами отметит инцидент как закрытый, откатите оба изменения: восстановите лимит расходов, сохранённый на шаге 1 (или удалите переопределение с помощью DELETE /v1/organizations/spend_limits/{spend_limit_id}, если у участника его не было), и удалите участника из группы с помощью DELETE /v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id}.

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

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

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

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

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

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

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

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

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

См. также