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}'



워크플로 예시

이러한 워크플로는 Spend Limits API와 Analytics API 비용 엔드포인트를 결합합니다. Analytics 비용 엔드포인트는 날짜 범위에 걸친 조직 전체 지출 리포팅을 위해 설계되었습니다. GET /spend_limits/effective는 현재 각 구성원에게 적용되는 한도를 반환합니다. Analytics로 스윕을 시작하여 살펴볼 구성원을 파악한 다음, /effective로 현재 한도를 조회하세요.

Spend Limits 엔드포인트에는 spend_limits 범위가 필요하고 Analytics 비용 엔드포인트에는 read:analytics가 필요합니다. 액세스 프로비저닝 방법은 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와 현재 유효 amount 및 period_to_date_spend가 포함된 실시간 spend_summary가 있어, 별도의 조회 없이 결정하기에 충분합니다.

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}'

   거부하려면 대신 .../{id}/deny로 POST하세요. 자체 시스템에서 요청자에게 알림을 보내는 경우 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"

   각 행에는 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"

   각 행은 period_to_date_spend와 함께 한도를 amount로 반환합니다(null = 무제한, "0" = 포함된 사용량만).

3. 양수 한도를 가진 각 구성원에 대해 period_to_date_spend / amount를 계산하고 임계값(예: 80%) 이상인 구성원을 표시합니다. "0" 한도는 이미 한도에 도달한 것으로 취급하세요. 이 비율에 대한 서버 측 필터는 없습니다.

4. 표시된 구성원에 대해 조치합니다. POST /v1/organizations/spend_limits로 한도를 상향하거나, 대기 중인 상향 요청이 있으면 승인하거나, 구성원에게 연락하세요.



사용량이 급격히 변하는 구성원 찾기

주간 대비 지출이 급증한 구성원을 찾아내세요.

1. Analytics API에서 지난 2주간의 구성원별 일일 비용을 가져옵니다.

   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로 행을 그룹화합니다. 각 구성원에 대해 최근 7일과 그 이전 7일을 합산합니다. 최근 주가 이전 주를 선택한 배수(예: 3배)만큼 초과하는 구성원을 표시합니다. 최근 날짜의 비용은 잠정적이며 상향 수정될 수 있습니다. 반복 가능한 비교를 위해서는 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"으로 표시됩니다. 참고용으로 취급하세요.



참고 자료