---
title: 사용량 및 비용 API
url: https://platform.claude.com/docs/ko/manage-claude/usage-cost-api
description: Usage and Cost Admin API를 사용하여 조직의 API 사용량 및 비용 데이터에 프로그래밍 방식으로 접근하세요.
---

<Tip>
  **Admin API는 개인 계정에서는 사용할 수 없습니다.** 팀원과 협업하고 멤버를 추가하려면 Claude Console의 [Organization](https://platform.claude.com/settings/organization) 페이지(`platform.claude.com/settings/organization`)에서 조직을 설정하세요.
</Tip>

Usage and Cost Admin API는 조직의 과거 API 사용량 및 비용 데이터에 대한 프로그래밍 방식의 세분화된 접근을 제공합니다. 이 데이터는 Claude Console의 [Usage](https://platform.claude.com/usage) 페이지(`platform.claude.com/usage`) 및 [Cost](https://platform.claude.com/cost) 페이지(`platform.claude.com/cost`)에서 확인할 수 있는 정보와 유사합니다.

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

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

<Check>
  **Admin API 자격 증명이 필요합니다.** 이 엔드포인트들은 Admin API의 일부입니다. [Admin API 키](https://platform.claude.com/docs/ko/manage-claude/admin-api-keys), `org:admin` 범위를 가진 OAuth 토큰, 또는 워크스페이스로 범위가 제한되지 않은 개인 또는 서비스 계정 키를 사용하여 접근할 수 있습니다. 워크스페이스 API 키는 작동하지 않습니다. 자세한 내용은 [인증](https://platform.claude.com/docs/ko/manage-claude/admin-api#authentication)을 참조하세요.
</Check>

Claude Enterprise 조직은 대신 다른 API와 함께 Analytics API 키를 사용합니다. [어떤 API가 필요한가요?](https://platform.claude.com/docs/ko/manage-claude/usage-cost-api#which-api-do-you-need)를 참조하세요.

<Note>
  **Claude Platform on AWS:** 프로그래밍 방식의 사용량 및 비용 API 엔드포인트는 현재 제공되지 않습니다. 대신 Claude Console의 **Usage** 및 **Cost** 페이지에서 사용량 및 비용 데이터를 확인하세요.
</Note>

## 어떤 API가 필요한가요?

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

| 조직 유형                            | API                                                                                                                    | 키 유형                                                                                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Console (Claude Platform) | 이 페이지에서 설명하는 Usage and Cost Admin API                                                                                  | Admin API 키(`sk-ant-admin01-...`) 또는 다른 [Admin API 자격 증명](https://platform.claude.com/docs/ko/manage-claude/admin-api#authentication) |
| Claude Enterprise (claude.ai)    | [Claude Enterprise Analytics API](https://platform.claude.com/docs/ko/api/beta/organization/analytics)의 비용 및 사용량 엔드포인트 | Analytics API 키                                                                                                                       |

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

## 파트너 솔루션

주요 관측성(observability) 플랫폼은 사용자 정의 코드를 작성하지 않고도 Claude API 사용량 및 비용을 모니터링할 수 있는 즉시 사용 가능한 통합 기능을 제공합니다. 이러한 통합 기능은 API 사용량을 효과적으로 관리하는 데 도움이 되는 대시보드, 알림 및 분석 기능을 제공합니다.

<CardGroup cols={3}>
  <Card title="CloudZero" icon="chart" href="https://docs.cloudzero.com/docs/connections-anthropic">
    비용 추적 및 예측을 위한 클라우드 인텔리전스 플랫폼
  </Card>

  <Card title="Datadog" icon="chart" href="https://docs.datadoghq.com/integrations/anthropic/">
    자동 추적 및 모니터링을 갖춘 LLM 관측성
  </Card>

  <Card title="Grafana Cloud" icon="chart" href="https://grafana.com/docs/grafana-cloud/monitor-infrastructure/integrations/integration-reference/integration-anthropic/">
    기본 제공 대시보드와 알림으로 손쉬운 LLM 관측성을 제공하는 에이전트리스 통합
  </Card>

  <Card title="Harness" icon="chart" href="https://developer.harness.io/docs/cloud-cost-management/provider-integrations/ai-providers/anthropic/">
    클라우드 및 AI 비용 관리를 위한 FinOps 플랫폼
  </Card>

  <Card title="Honeycomb" icon="polygon" href="https://docs.honeycomb.io/integrations/anthropic-usage-monitoring/">
    OpenTelemetry를 통한 고급 쿼리 및 시각화
  </Card>

  <Card title="Tempo" icon="chart" href="https://help.tempo.io/workforceintelligence/latest/connect-to-anthropic">
    Jira 작업 항목에 대한 사용량 및 비용 귀속
  </Card>

  <Card title="Vantage" icon="chart" href="https://docs.vantage.sh/connecting_anthropic">
    LLM 비용 및 사용량 관측성을 위한 FinOps 플랫폼
  </Card>
</CardGroup>

## 빠른 시작

지난 7일간 조직의 일일 사용량을 조회합니다:

```bash cURL
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"
```

<Tip>
  **통합을 위한 User-Agent 헤더 설정**

  통합 기능을 구축하는 경우, Anthropic이 사용 패턴을 파악할 수 있도록 User-Agent 헤더를 설정하세요:

  ```text wrap
  User-Agent: YourApp/1.0.0 (https://yourapp.com)
  ```
</Tip>

## Usage API

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

### 주요 개념

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

전체 매개변수 세부 정보 및 응답 스키마는 [Usage API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization/usage_report/retrieve_messages)를 참조하세요.

### 기본 예제

#### 모델별 일일 사용량

```bash cURL
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"
```

#### 필터링을 적용한 시간별 사용량

```bash cURL
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_ADMIN_KEY"
```

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

```bash cURL
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"
```

<Tip>
  조직의 API 키 ID를 조회하려면 [List API Keys](https://platform.claude.com/docs/ko/api/organization/api_keys/list) 엔드포인트를 사용하세요.

  조직의 워크스페이스 ID를 조회하려면 [List Workspaces](https://platform.claude.com/docs/ko/api/organization/workspaces/list) 엔드포인트를 사용하거나, Claude Console에서 조직의 워크스페이스 ID를 확인하세요.
</Tip>

#### 데이터 레지던시

`inference_geo` 차원으로 사용량을 그룹화하고 필터링하여 [데이터 레지던시 제어](https://platform.claude.com/docs/ko/manage-claude/data-residency)를 추적하세요. 이는 조직 전체의 지리적 라우팅을 검증하는 데 유용합니다.

```bash cURL
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`입니다:

```bash cURL
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"
```

<Note>
  2026년 2월 이전에 출시된 모델(Claude Opus 4.6 및 Claude Sonnet 4.6 이전)은 `inference_geo` 요청 매개변수를 지원하지 않으므로, 해당 모델의 사용량 보고서는 이 차원에 대해 `"not_available"`을 반환합니다. `inference_geos[]`에서 `not_available`을 필터 값으로 사용하여 해당 모델을 대상으로 지정할 수 있습니다.
</Note>

#### Fast mode

`speed` 차원으로 그룹화하고 필터링하여 [fast mode](https://platform.claude.com/docs/ko/build-with-claude/fast-mode) 사용량을 추적하세요. 이는 표준 모드와 fast mode 사용량을 비교 모니터링하는 데 유용합니다.

```bash cURL
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 "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

특정 속도로 필터링할 수도 있습니다. 유효한 값은 `standard` 및 `fast`입니다:

```bash cURL
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 "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

### 시간 세분성 제한

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

## Cost API

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

### 주요 개념

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

전체 매개변수 세부 정보 및 응답 스키마는 [Cost API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization/cost_report/retrieve)를 참조하세요.

<Warning>
  Priority Tier 비용은 다른 청구 모델을 사용하며 비용 엔드포인트에 포함되지 않습니다. 대신 사용량 엔드포인트를 통해 Priority Tier 사용량을 추적하세요.
</Warning>

### 기본 예제

```bash cURL
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`가 될 때까지 계속합니다.

```bash cURL
# 첫 번째 요청
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](https://platform.claude.com/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](https://platform.claude.com/docs/ko/manage-claude/claude-code-analytics-api)를 사용하세요. 이 API는 많은 API 키별로 비용을 분석할 때 발생하는 성능 제한 없이 사용자별 예상 비용과 생산성 지표를 제공합니다. 많은 키를 사용하는 일반 API 사용량의 경우, [Usage API](https://platform.claude.com/docs/ko/manage-claude/usage-cost-api#usage-api)를 사용하여 비용 대용 지표로 토큰 소비량을 추적하세요.

## 참고 항목

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

* [Admin API](https://platform.claude.com/docs/ko/manage-claude/admin-api)
* [Admin API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization)
* [Analytics API](https://platform.claude.com/docs/ko/manage-claude/analytics-api) - 조직에 필요한 분석 API 및 키 유형
* [가격](https://platform.claude.com/docs/ko/about-claude/pricing)
* [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching) - 캐싱으로 비용 최적화
* [배치 처리](https://platform.claude.com/docs/ko/build-with-claude/batch-processing) - 배치 요청 50% 할인
* [속도 제한](https://platform.claude.com/docs/ko/api/rate-limits) - 사용량 티어 이해하기
* [Rate Limits API](https://platform.claude.com/docs/ko/manage-claude/rate-limits-api) - 구성된 속도 제한 조회
* [데이터 레지던시](https://platform.claude.com/docs/ko/manage-claude/data-residency) - 추론 지역 제어