Usage and Cost API

Usage and Cost API

Usage & Cost Admin API는 조직의 과거 API 사용량과 비용 데이터에 프로그래밍 방식으로, 그리고 세밀하게 접근하게 해 주는 API예요. 이 데이터는 Claude Console의 Usage와 Cost 페이지에서 볼 수 있는 정보와 비슷해요.

이 API로 Claude 구현을 더 잘 모니터링·분석·최적화할 수 있어요:

  • 정확한 사용량 추적: 응답 토큰 계산에만 의존하는 대신 정밀한 토큰 수와 사용 패턴을 얻을 수 있어요.
  • 비용 조정: 재무·회계 팀이 내부 기록을 Anthropic 청구와 맞출 수 있어요.
  • 제품 성능과 개선: 시스템 변경이 개선됐는지 측정하면서 제품 성능을 모니터링하거나 알림을 설정할 수 있어요.
  • 속도 제한 최적화: 프롬프트 캐싱 같은 기능이나 특정 프롬프트를 최적화해 할당된 용량을 최대한 활용할 수 있어요.
  • 고급 분석: Console에서 제공하는 것보다 더 깊은 데이터 분석을 수행할 수 있어요.

Admin API 자격 증명 필요 이 엔드포인트들은 Admin API에 속해요. Admin API 키, org:admin 범위의 OAuth 토큰, 또는 워크스페이스에 범위가 제한되지 않은 개인·서비스 계정 키로 접근할 수 있어요. 워크스페이스 API 키는 작동하지 않아요. 자세한 내용은 인증을 참고하세요.

Claude Enterprise 조직은 다른 API로 Analytics API 키를 사용해요. 어떤 API가 필요할까?를 참고하세요.

참고 AWS의 Claude Platform: 프로그래밍 방식의 Usage and Cost API 엔드포인트는 현재 사용할 수 없어요. 대신 Claude Console의 Usage와 Cost 페이지에서 사용량·비용 데이터를 보세요.

출처: 문서

본문

어떤 API가 필요할까?

Anthropic은 조직이 관리하는 Claude 제품에 따라 두 가지 API를 통해 비용·사용량 보고를 제공해요:

조직 API 키 타입
Claude Console (Claude Platform) 이 페이지에 설명된 Usage and Cost Admin API Admin API 키(«redacted:sk-…»...) 또는 다른 Admin API 자격 증명
Claude Enterprise (claude.ai) Claude Enterprise Analytics API 비용·사용량 엔드포인트 Analytics API 키

Claude Enterprise 상위 조직은 Claude Console에 나타나지 않고 Admin API 키를 지니지 않으므로, 그들에게는 Analytics API 키가 이 데이터로 가는 유일한 경로예요. 각 키 타입을 만드는 방법과 Claude Enterprise 비용 데이터가 적용되는 플랜은 Analytics APIs를 참고하세요.

파트너 솔루션

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

  • CloudZero — 비용 추적·예측을 위한 클라우드 인텔리전스 플랫폼.
  • Datadog — 자동 추적·모니터링을 갖춘 LLM Observability.
  • Grafana Cloud — 즉시 사용 가능한 대시보드·알림으로 쉬운 LLM 관측을 위한 에이전트리스 통합.
  • Harness — 클라우드·AI 비용 관리를 위한 FinOps 플랫폼.
  • Honeycomb — OpenTelemetry를 통한 고급 쿼리와 시각화.
  • Vantage — LLM 비용·사용량 관측을 위한 FinOps 플랫폼.

빠른 시작

조직의 지난 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

팁 통합을 위한 User-Agent 헤더 설정 통합을 만들고 있다면, Anthropic이 사용 패턴을 이해하도록 User-Agent 헤더를 설정하세요:

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

Usage API

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

핵심 개념

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

전체 파라미터 세부사항과 응답 스키마는 Usage API reference를 참고하세요.

기본 예시

모델별 일별 사용량

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_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-5-5&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

팁 조직의 API 키 ID를 가져오려면 List API Keys 엔드포인트를 사용하세요.

조직의 워크스페이스 ID를 가져오려면 List Workspaces 엔드포인트를 사용하거나 Claude Console에서 조직의 워크스페이스 ID를 찾을 수 있어요.

데이터 레지던시

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

참고 2026년 2월 이전(Claude Opus 4.6과 Claude Sonnet 4.6 이전)에 출시된 모델은 inference_geo 요청 파라미터를 지원하지 않으므로, 그들의 사용량 보고는 이 차원에 대해 "not_available"을 반환해요. inference_geos[]에서 필터 값으로 not_available을 사용해 그 모델들을 대상으로 할 수 있어요.

패스트 모드(리서치 프리뷰)

speed 차원으로 그룹화·필터링해 패스트 모드 사용량을 추적해요. 표준 모드와 패스트 모드 사용량을 모니터링하는 데 유용해요.

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[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

특정 속도로 필터링할 수도 있어요. 유효한 값은 standard와 fast이에요:

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

참고 speeds[] 필터와 speed group_by 값 모두 fast-mode-2026-02-01 베타 헤더가 필요해요.

시간 세분화 제한

세분화 기본 제한 최대 제한 사용 사례
1m 60 버킷 1,440 버킷 실시간 모니터링
1h 24 버킷 168 버킷 일별 패턴
1d 7 버킷 31 버킷 주간/월간 보고

Cost API

/v1/organizations/cost_report 엔드포인트로 USD의 서비스 수준 비용 분류를 가져와요.

핵심 개념

  • 통화: 모든 비용은 USD이며, 최소 단위(센트)의 십진 문자열로 보고돼요.
  • 비용 타입: 토큰 사용량, 웹 검색, 코드 실행 비용을 추적해요.
  • 그룹화: 워크스페이스나 설명(description)으로 비용을 그룹화해 상세 분류를 얻어요. description으로 그룹화하면 model, inference_geo 같은 파싱된 필드가 응답에 포함돼요.
  • 시간 버킷: 일별 세분화(1d)만 지원해요.

전체 파라미터 세부사항과 응답 스키마는 Cost API reference를 참고하세요.

경고 Priority Tier 비용은 다른 청구 모델을 사용하며 비용 엔드포인트에 포함되지 않아요. Priority Tier 사용량은 사용량 엔드포인트를 통해 추적하세요.

기본 예시

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

페이지네이션

두 엔드포인트 모두 대용량 데이터셋에 페이지네이션을 지원해요:

  1. 첫 요청을 보내세요.
  2. has_more가 true면 다음 요청에서 next_page 값을 사용하세요.
  3. has_more가 false가 될 때까지 계속하세요.
# First request
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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

# Response includes: "has_more": true, "next_page": "page_xyz..."

# Next request with pagination
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..." \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

일반적인 사용 사례

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

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

자주 묻는 질문

데이터는 얼마나 신선한가요?

사용량·비용 데이터는 보통 API 요청 완료 후 5분 이내에 나타나며, 가끔 지연이 더 길 수도 있어요.

권장 폴링 빈도는?

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

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

코드 실행 비용은 cost 엔드포인트에서 description 필드의 Code Execution Usage 아래 그룹으로 나타나요. 코드 실행은 usage 엔드포인트에 포함되지 않아요.

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

usage 엔드포인트에서 service_tier로 필터·그룹화하고 priority 값을 찾으세요. Priority Tier 비용은 cost 엔드포인트에서 사용할 수 없어요.

플레이그라운드 사용량은 어떻게 되나요?

Claude Console의 플레이그라운드(그리고 그 이전의 레거시 Workbench)에서 온 API 사용량은 API 키와 연결되지 않으므로, 그 차원으로 그룹화해도 api_key_id가 null이 돼요.

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

기본 워크스페이스에 귀속된 사용량·비용은 workspace_id 값이 null이에요.

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

Claude Code Analytics API를 사용하세요. 많은 API 키로 비용을 분류할 때의 성능 제한 없이 사용자별 추정 비용과 생산성 지표를 제공해요. 많은 키가 있는 일반 API 사용량에는 Usage API를 사용해 비용 대리 지표로 토큰 소비를 추적하세요.

함께 보기

Usage and Cost API를 사용해 사용자에게 더 나은 경험을 제공하고, 비용을 관리하며, 속도 제한을 보존하세요. 이 다른 기능들에 대해 더 알아보세요:

더 알아보기 (Learn more)