사용량 및 비용 API

사용량 및 비용 Admin API는 조직의 과거 API 사용량 및 비용 데이터에 대한 프로그래밍 방식의 세분화된 접근을 제공합니다. 이 데이터는 Claude Console의 Usage 및 Cost 페이지에서 확인할 수 있는 정보와 유사합니다.

이 API를 통해 Claude 구현을 더 잘 모니터링, 분석 및 최적화할 수 있습니다:

• 정확한 사용량 추적: 응답 토큰 카운팅에만 의존하지 않고 정확한 토큰 수와 사용 패턴을 확인
• 비용 조정: 재무 및 회계 팀을 위해 내부 기록을 Anthropic 청구서와 대조
• 제품 성능 및 개선: 제품 성능을 모니터링하면서 시스템 변경이 개선을 가져왔는지 측정하거나 알림 설정
• 속도 제한 및 Priority Tier 최적화: 프롬프트 캐싱이나 특정 프롬프트와 같은 기능을 최적화하여 할당된 용량을 최대한 활용하거나 전용 용량을 구매
• 고급 분석: Console에서 제공하는 것보다 더 심층적인 데이터 분석 수행

파트너 솔루션

주요 관측성 플랫폼은 커스텀 코드를 작성하지 않고도 Claude API 사용량과 비용을 모니터링할 수 있는 즉시 사용 가능한 통합을 제공합니다. 이러한 통합은 대시보드, 알림 및 분석을 제공하여 API 사용량을 효과적으로 관리할 수 있도록 도와줍니다.

빠른 시작

지난 7일간 조직의 일별 사용량을 가져옵니다:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-15T00:00:00Z&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

User-Agent: YourApp/1.0.0 (https://yourapp.com)

사용량 API

/v1/organizations/usage_report/messages 엔드포인트를 통해 모델, 워크스페이스, 서비스 티어별 상세 분류와 함께 조직 전체의 토큰 소비를 추적합니다.

주요 개념

• 시간 버킷: 고정 간격(1m, 1h, 또는 1d)으로 사용량 데이터 집계
• 토큰 추적: 캐시되지 않은 입력, 캐시된 입력, 캐시 생성 및 출력 토큰 측정
• 필터링 및 그룹화: API 키, 워크스페이스, 모델, 서비스 티어, 컨텍스트 윈도우 또는 데이터 레지던시별로 필터링하고 이러한 차원별로 결과를 그룹화
• 서버 도구 사용량: 웹 검색과 같은 서버 측 도구의 사용량 추적

전체 매개변수 세부 정보 및 응답 스키마는 사용량 API 레퍼런스를 참조하세요.

기본 예제

모델별 일별 사용량

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

필터링을 포함한 시간별 사용량

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-15T00:00:00Z&\
ending_at=2025-01-15T23:59:59Z&\
models[]=claude-opus-4-6&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

API 키 및 워크스페이스별 사용량 필터링

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\
api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

데이터 레지던시

inference_geo 차원으로 사용량을 그룹화하고 필터링하여 데이터 레지던시 제어를 추적합니다. 이는 조직 전체의 지리적 라우팅을 확인하는 데 유용합니다.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=inference_geo&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

특정 지역으로 필터링할 수도 있습니다. 유효한 값은 global, us, not_available입니다:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
inference_geos[]=us&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

시간 세분화 제한

비용 API

/v1/organizations/cost_report 엔드포인트를 통해 USD 단위의 서비스 수준 비용 분류를 가져옵니다.

주요 개념

• 통화: 모든 비용은 USD로, 최소 단위(센트)의 소수점 문자열로 보고
• 비용 유형: 토큰 사용량, 웹 검색 및 코드 실행 비용 추적
• 그룹화: 상세 분류를 위해 워크스페이스 또는 설명별로 비용 그룹화. description별로 그룹화할 때 응답에는 model 및 inference_geo와 같은 파싱된 필드가 포함됨
• 시간 버킷: 일별 세분화만 가능(1d)

전체 매개변수 세부 정보 및 응답 스키마는 비용 API 레퍼런스를 참조하세요.

기본 예제

curl "https://api.anthropic.com/v1/organizations/cost_report?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
group_by[]=workspace_id&\
group_by[]=description" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

페이지네이션

두 엔드포인트 모두 대규모 데이터셋에 대한 페이지네이션을 지원합니다:

1. 초기 요청을 수행합니다
2. has_more가 true이면 다음 요청에서 next_page 값을 사용합니다
3. has_more가 false가 될 때까지 계속합니다

# 첫 번째 요청
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

# 응답에 포함: "has_more": true, "next_page": "page_xyz..."

# 페이지네이션을 포함한 다음 요청
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7&\
page=page_xyz..." \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

일반적인 사용 사례

Claude Cookbook에서 상세한 구현을 살펴보세요:

• 일별 사용량 보고서: 토큰 소비 추세 추적
• 비용 귀속: 차지백을 위한 워크스페이스별 비용 할당
• 캐시 효율성: 프롬프트 캐싱 측정 및 최적화
• 예산 모니터링: 지출 임계값에 대한 알림 설정
• CSV 내보내기: 재무 팀을 위한 보고서 생성

자주 묻는 질문

데이터는 얼마나 최신인가요?

사용량 및 비용 데이터는 일반적으로 API 요청 완료 후 5분 이내에 표시되지만, 간혹 지연이 더 길어질 수 있습니다.

권장 폴링 빈도는 어떻게 되나요?

API는 지속적인 사용을 위해 분당 1회 폴링을 지원합니다. 짧은 버스트(예: 페이지네이션된 데이터 다운로드)의 경우 더 빈번한 폴링이 허용됩니다. 자주 업데이트가 필요한 대시보드의 경우 결과를 캐시하세요.

코드 실행 사용량은 어떻게 추적하나요?

코드 실행 비용은 비용 엔드포인트에서 description 필드의 Code Execution Usage로 그룹화되어 표시됩니다. 코드 실행은 사용량 엔드포인트에는 포함되지 않습니다.

Priority Tier 사용량은 어떻게 추적하나요?

사용량 엔드포인트에서 service_tier로 필터링하거나 그룹화하고 priority 값을 찾으세요. Priority Tier 비용은 비용 엔드포인트에서 사용할 수 없습니다.

Workbench 사용량은 어떻게 되나요?

Workbench에서의 API 사용량은 API 키와 연결되지 않으므로, 해당 차원으로 그룹화하더라도 api_key_id는 null이 됩니다.

기본 워크스페이스는 어떻게 표시되나요?

기본 워크스페이스에 귀속된 사용량 및 비용은 workspace_id에 대해 null 값을 가집니다.

Claude Code의 사용자별 비용 분류는 어떻게 얻나요?

많은 API 키별로 비용을 분류할 때의 성능 제한 없이 사용자별 예상 비용과 생산성 지표를 제공하는 Claude Code Analytics API를 사용하세요. 많은 키를 사용하는 일반 API 사용량의 경우, 사용량 API를 사용하여 비용 대리 지표로 토큰 소비를 추적하세요.

참고 자료

사용량 및 비용 API를 활용하면 사용자에게 더 나은 경험을 제공하고, 비용을 관리하며, 속도 제한을 보존하는 데 도움이 됩니다. 이러한 다른 기능에 대해 자세히 알아보세요:

• Admin API 개요
• Admin API 레퍼런스
• 가격 정책
• 프롬프트 캐싱 - 캐싱으로 비용 최적화
• 배치 처리 - 배치 요청 50% 할인
• 속도 제한 - 사용량 티어 이해
• 데이터 레지던시 - 추론 지역 제어