사용량 및 비용 API

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

이 API를 사용하면 Claude 구현을 더 효과적으로 모니터링, 분석 및 최적화할 수 있습니다:

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

Claude Enterprise 조직은 대신 다른 API와 함께 Analytics API 키를 사용합니다. 어떤 API가 필요한가요?를 참조하세요.

어떤 API가 필요한가요?

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

Claude Enterprise 상위 조직은 Claude Console에 표시되지 않으며 Admin API 키를 보유하지 않으므로, 이러한 조직의 경우 Analytics API 키가 이 데이터에 접근할 수 있는 유일한 경로입니다. 각 키 유형을 생성하는 방법과 Claude Enterprise 비용 데이터가 적용되는 플랜에 대해서는 Analytics API를 참조하세요.

파트너 솔루션

주요 관측성(observability) 플랫폼은 사용자 정의 코드를 작성하지 않고도 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Usage API

/v1/organizations/usage_report/messages 엔드포인트를 사용하여 모델, 워크스페이스 및 서비스 티어별 상세 분석과 함께 조직 전체의 토큰 소비량을 추적하세요.

주요 개념

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

전체 매개변수 세부 정보 및 응답 스키마는 Usage 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_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&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_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_ADMIN_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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_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_ADMIN_KEY"

Fast mode (리서치 프리뷰)

speed 차원으로 그룹화하고 필터링하여 fast mode 사용량을 추적하세요. 이는 표준 모드와 fast mode 사용량을 비교 모니터링하는 데 유용합니다.

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_ADMIN_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_ADMIN_KEY"

시간 세분성 제한

Cost API

/v1/organizations/cost_report 엔드포인트를 사용하여 서비스 수준의 비용 분석을 USD로 조회하세요.

주요 개념

• 통화: 모든 비용은 USD이며, 최소 단위(센트)의 십진수 문자열로 보고됩니다
• 비용 유형: 토큰 사용량, 웹 검색 및 코드 실행 비용을 추적합니다
• 그룹화: 상세 분석을 위해 워크스페이스 또는 설명별로 비용을 그룹화합니다. description으로 그룹화하면 응답에 model 및 inference_geo와 같은 파싱된 필드가 포함됩니다
• 시간 버킷: 일일 세분성만 지원(1d)

전체 매개변수 세부 정보 및 응답 스키마는 Cost 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_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..." \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

일반적인 사용 사례

Claude Cookbook에서 상세한 구현 예제를 살펴보세요:

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

자주 묻는 질문

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

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

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

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

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

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

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

사용량 엔드포인트에서 service_tier로 필터링하거나 그룹화한 후 priority 값을 찾으세요. Priority Tier 비용은 비용 엔드포인트에서 제공되지 않습니다.

playground 사용량은 어떻게 처리되나요?

Claude Console의 playground(및 그 이전의 레거시 Workbench)에서 발생한 API 사용량은 API 키와 연결되지 않으므로, 해당 차원으로 그룹화하더라도 api_key_id는 null이 됩니다.

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

기본 워크스페이스에 귀속된 사용량 및 비용은 workspace_id 값이 null입니다.

Claude Code의 사용자별 비용 분석은 어떻게 얻나요?

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

참고 항목

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

• Admin API
• Admin API 레퍼런스
• Analytics API - 조직에 필요한 분석 API 및 키 유형
• 가격
• 프롬프트 캐싱 - 캐싱으로 비용 최적화
• 배치 처리 - 배치 요청 50% 할인
• 속도 제한 - 사용량 티어 이해하기
• Rate Limits API - 구성된 속도 제한 조회
• 데이터 레지던시 - 추론 지역 제어