Spend Limits API

Spend Limits API를 사용하면 각 Claude Enterprise 구성원에게 지출 한도를 설정하고, 각 구성원의 지출 한도가 어디에서 상속되는지 확인하며, 구성원의 한도 상향 요청을 검토하거나 처리할 수 있습니다.

사용자별 및 시간 구간별 사용량과 비용 리포팅에 대해서는 Analytics 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)는 범위 수준의 계층 구조에서 결정되어 각 구성원의 지출에 적용됩니다. 구성원에게 사용자별 재정의가 없는 경우, 해당 구성원은 자신의 그룹(조직이 그룹 기반 한도를 사용하는 경우), 시트 티어 또는 조직 전체 기본값에 구성된 지출 한도를 상속받습니다. 그룹 지출 한도는 구성원별 기본값입니다. 즉, 이를 상속받는 각 구성원은 공유된 그룹 예산이 아니라 자신의 지출을 기준으로 제한됩니다.

GET /v1/organizations/spend_limits/effective를 조회하면 모든 현재 구성원과 함께 결정된 유효 지출 한도, 해당 한도가 결정된 출처(source), 현재 기간 누적 지출이 반환됩니다. POST /v1/organizations/spend_limits로 사용자별 재정의를 설정하면 구성원이 상속받을 값과 관계없이 특정 지출 한도로 고정됩니다. 재정의를 삭제하면 상속된 지출 한도로 돌아가거나, 상속할 한도가 없는 경우 무제한 상태가 됩니다.

각 구성원 행의 source 필드는 해당 지출 한도가 어느 수준에서 결정되었는지 알려줍니다. user(사용자별 재정의), seat_tier, rbac_group 또는 organization입니다. 범위 유형은 개방형 집합으로 취급하세요. 알 수 없는 값에 대해서는 실패하지 말고 통과시키세요.



기간

period는 지출 한도가 적용되고 지출이 초기화되는 반복 기간입니다. 지출 한도는 (scope, period) 쌍으로 식별됩니다. 현재 monthly가 유일하게 지원되는 기간이며, 월간 지출은 매월 1일 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"으로 표시될 수 있으므로, 트랜잭션용이 아닌 참고용으로 취급하세요.



상향 요청 수명 주기

지출 한도 상향 요청은 구성원이 claude.ai에서 Request more usage(추가 사용량 요청)를 클릭할 때 생성됩니다. 요청은 이 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는 불투명 커서(opaque cursor)로 페이지네이션됩니다. 첫 번째 요청은 최대 limit개의 행과 next_page 커서를 반환합니다. 해당 커서를 변경하지 않고 다음 요청의 page 매개변수로 전달하고, next_page가 null이 될 때까지 반복하세요.

시퀀스 중간에 쿼리 매개변수를 변경하지 마세요. 커서는 해당 커서를 발급한 필터에 바인딩됩니다. user_ids[], period[], status[] 또는 actor_ids[]를 변경하고 이전 커서를 전달하면 "cursor does not match current query parameters" 메시지와 함께 400 오류가 발생합니다. 대신 첫 페이지부터 새 시퀀스를 시작하세요.



목록 매개변수 직렬화

목록 매개변수는 대괄호 표기법을 사용합니다. 각 값마다 []를 붙여 매개변수 이름을 반복하세요.

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}는 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는 사용자별 지출 한도 재정의를 설정합니다. 이는 (scope, period)를 키로 하는 upsert입니다. 이미 한도가 있는 사용자와 기간에 대해 한도를 설정하면 기존 값을 덮어씁니다. 이 엔드포인트는 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}는 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"으로 표시됩니다. 참고용으로 취급하세요.



참고 항목