Spend Limits API

Spend Limits API를 사용하면 각 Claude Enterprise 멤버에게 "spend limit"(지출 한도)을 설정하고, 각 멤버의 지출 한도가 어디에서 상속되는지 확인하며, 더 높은 한도를 요청하는 멤버의 요청을 검토하거나 처리할 수 있습니다.

사용자별 및 시간 버킷별 사용량과 비용 보고에 대해서는 Analytics API를 참조하세요.

개요

이 API는 두 가지 리소스에 걸쳐 8개의 엔드포인트를 제공합니다:

지출 한도 엔드포인트는 "각 멤버에게 어떤 지출 한도가 적용되며, 그 한도는 어디에서 오고, 멤버가 한도에 얼마나 근접했는가?"라는 질문에 답하고 사용자별 재정의를 설정하는 데 사용하세요. 지출 한도 증액 요청 엔드포인트는 멤버가 제출한 요청 대기열을 처리하는 데 사용하세요.

사전 요구 사항

• 조직이 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"(유효 지출 한도)이 적용됩니다. 멤버에게 사용자별 재정의가 없는 경우, 해당 멤버는 그룹(조직이 그룹 기반 한도를 사용하는 경우), 시트 티어 또는 조직 전체 기본값에 구성된 지출 한도를 상속합니다. 그룹 지출 한도는 멤버별 기본값입니다. 이를 상속하는 각 멤버는 공동 그룹 예산이 아닌 자신의 지출을 기준으로 제한됩니다.

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: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"으로 표시될 수 있으므로, 트랜잭션용이 아닌 정보용으로 취급하세요.

증액 요청 수명 주기

지출 한도 증액 요청은 멤버가 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를 전달하세요.

버전 관리

모든 요청에 anthropic-version 헤더를 보내세요. 사용 가능한 버전은 API 버전을 참조하세요.

속도 제한

8개 엔드포인트 모두 분당 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[]를 변경하고 이전 커서를 전달하면 "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" \
  --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}는 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는 사용자별 지출 한도 재정의를 설정합니다. 이는 (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" \
  --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}는 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 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 --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와 현재 유효 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" \
     --header "anthropic-version: 2023-06-01" \
     --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" \
     --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"

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

   bucket_width가 설정되면 각 멤버는 사용량이 있는 날마다 하나의 행을 차지합니다. 모든 멤버의 전체 시계열을 수집하려면 next_page로 페이지를 넘기세요.

2. actor.user_id로 행을 그룹화합니다. 각 멤버에 대해 최근 7일과 이전 7일을 합산합니다. 최근 주가 이전 주를 선택한 배수(예: 3배)만큼 초과하는 멤버를 표시합니다. 최근 일자의 비용은 잠정적이며 상향 수정될 수 있습니다. 반복 가능한 비교를 위해서는 ending_at을 이전에 반환된 data_refreshed_at 이전 또는 같은 시점으로 설정하세요(데이터 가용성 및 최신성 참조).

3. 표시된 멤버에 대해 조치합니다. POST /v1/organizations/spend_limits로 상한을 조정하거나 연락하세요.

인시던트 중 멤버의 지출 한도를 일시적으로 상향

인시던트가 열려 있는 동안 인시던트 대응자에게 작업할 여유를 제공합니다. 인시던트가 시작되면 지출 상한을 올리고, 인시던트가 종료된 후 롤백합니다. 예를 들어 멤버가 할당된 활성 인시던트 ID를 요구하는 등, 인시던트 관리 시스템을 기준으로 상향을 제어하세요.

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"으로 표시됩니다. 정보용으로 취급하세요.

참고 항목