사용량 및 비용 API

사용량 및 비용 관리자 API는 조직의 과거 API 사용량 및 비용 데이터에 대한 프로그래밍 방식의 세분화된 액세스를 제공합니다. 이 데이터는 Anthropic Console의 사용량 및 비용 페이지에서 제공되는 정보와 유사합니다.

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

• 정확한 사용량 추적: 응답 토큰 카운팅에만 의존하지 않고 정확한 토큰 수와 사용 패턴을 얻습니다
• 비용 조정: 재무 및 회계 팀을 위해 내부 기록을 Anthropic 청구서와 일치시킵니다
• 제품 성능 및 개선: 시스템 변경이 개선되었는지 측정하면서 제품 성능을 모니터링하거나 알림을 설정합니다
• 속도 제한 및 우선순위 계층 최적화: 프롬프트 캐싱이나 특정 프롬프트와 같은 기능을 최적화하여 할당된 용량을 최대한 활용하거나 전용 용량을 구매합니다.
• 고급 분석: 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-sonnet-4-20250514&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

​

시간 세분성 제한

​

비용 API

/v1/organizations/cost_report 엔드포인트를 통해 USD 단위의 서비스 수준 비용 분석을 검색합니다.

​

주요 개념

• 통화: 모든 비용은 USD로 표시되며 최소 단위(센트)의 십진수 문자열로 보고됩니다
• 비용 유형: 토큰 사용량, 웹 검색 및 코드 실행 비용을 추적합니다
• 그룹화: 세부 분석을 위해 작업 공간 또는 설명별로 비용을 그룹화합니다
• 시간 버킷: 일일 세분성만 가능(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"

​

일반적인 사용 사례

anthropic-cookbook에서 세부 구현을 살펴보세요:

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

​

자주 묻는 질문

​

데이터는 얼마나 최신입니까?

사용량 및 비용 데이터는 일반적으로 API 요청 완료 후 5분 이내에 나타나지만 때때로 지연이 더 길 수 있습니다.

​

권장 폴링 빈도는 무엇입니까?

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

​

코드 실행 사용량을 어떻게 추적합니까?

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

​

우선순위 계층 사용량을 어떻게 추적합니까?

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

​

Workbench 사용량은 어떻게 됩니까?

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

​

기본 작업 공간은 어떻게 표현됩니까?

기본 작업 공간에 귀속된 사용량 및 비용은 workspace_id에 대해 null 값을 가집니다.

​

참고 항목

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

• 관리자 API 개요
• 관리자 API 참조
• 가격 책정
• 프롬프트 캐싱 - 캐싱으로 비용 최적화
• 배치 처리 - 배치 요청에 대한 50% 할인
• 속도 제한 - 사용량 계층 이해