Usage and Cost Analytics API

Usage and Cost Analytics API는 조직의 과거 토큰 사용량과 비용을 모델, 워크스페이스, API 키 또는 각 요청을 보낸 사용자나 서비스 계정 등 선택한 차원별로 나누어 보고합니다. Claude Console 조직의 경우 이 데이터는 Claude Console의 Usage 및 Cost 페이지에 표시되는 내용과 유사합니다.

이 API에는 두 개의 엔드포인트가 있습니다:

• GET /v1/organizations/analytics/usage는 토큰 수와 요청 수를 보고합니다.
• GET /v1/organizations/analytics/cost는 USD 단위의 비용을 보고합니다.

Usage and Cost Analytics API는 베타 버전입니다. 모든 요청에 anthropic-beta: analytics-usage-cost-2026-08-24 헤더와 anthropic-version 헤더를 보내세요. SDK와 ant CLI는 두 헤더를 자동으로 보내고 결과를 읽는 동안 나머지 페이지를 가져오므로, limit은 페이지 크기만 설정합니다.

이 API를 사용하여 다음을 수행할 수 있습니다:

• 지출 귀속: 워크스페이스, API 키, 모델, 서비스 티어 또는 각 요청을 보낸 ID별로 비용과 토큰 사용량을 세분화합니다.
• 상위 소비자 찾기: 토큰, 요청 또는 비용을 기준으로 결과의 순위를 매겨 "이번 달에 가장 많이 지출한 API 키는 무엇인가?"와 같은 질문에 답합니다.
• 시계열 구축: 대시보드와 재무 보고서를 위해 결과를 일별, 시간별 또는 분별 버킷으로 나눕니다.
• 한 번의 통합: 동일한 엔드포인트, 매개변수, 응답 필드가 Claude Console 조직과 Claude Enterprise 조직 모두에 제공됩니다.

빠른 시작

9월 첫째 주의 일별 토큰 사용량을 모델과 날짜별로 한 행씩 가져옵니다:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=10,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

응답에는 사용량이 있는 모델과 날짜마다 한 행이 포함되며, total_tokens가 가장 큰 행이 먼저 나옵니다. 이 예시는 단일 행을 보여줍니다:

{
  "data": [
    {
      "starting_at": "2026-09-03T00:00:00Z",
      "ending_at": "2026-09-04T00:00:00Z",
      "group": {
        "product": null,
        "model": "claude-sonnet-5",
        "context_window": null,
        "inference_geo": null,
        "speed": null,
        "slack_channel_id": null,
        "claude_tag_category": null,
        "claude_tag_user_id": null,
        "rbac_group_id": null,
        "workspace_id": null,
        "service_tier": null,
        "user_profile_id": null,
        "agent_id": null,
        "environment_id": null,
        "deployment_id": null,
        "session_id": null,
        "actor": null,
        "actor_type": null,
        "api_key_id": null
      },
      "usage": {
        "uncached_input_tokens": 1284500,
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 215300
        },
        "cache_read_input_tokens": 3200000,
        "output_tokens": 891000,
        "total_tokens": 5590800,
        "server_tool_use": {
          "web_search_requests": 12
        },
        "requests": 4210
      }
    }
  ],
  "has_more": true,
  "next_page": "page_V2mQ4dkt9HcbX3pLr...",
  "data_refreshed_at": "2026-09-18T16:02:11Z"
}

결과의 구성 방식

• 모든 행은 세 부분으로 구성됩니다: starting_at과 ending_at은 행이 다루는 기간을 나타내고, group은 모든 차원을 담으며, usage(비용 엔드포인트에서는 cost)는 지표를 담습니다.
• 그룹화하지 않은 차원은 null입니다: group의 차원은 group_by[]에 나열하지 않는 한 null입니다. 그룹화된 차원도 해당 값이 없는 행에서는 null이며, 예를 들어 코드 실행 사용량의 model이 그렇습니다. group_by[]는 최대 5개의 차원을 받습니다.
• 조합마다 한 행: 각 행은 그룹화된 차원의 한 조합이며, 사용량이나 비용이 있는 모든 조합은 쿼리의 전체 페이지에 걸쳐 정확히 한 번 나타납니다. group_by[]와 time_bucket_width가 모두 없으면 응답은 전체 범위를 합산한 단일 행입니다.
• 시간 버킷은 선택 사항입니다: time_bucket_width를 1m, 1h 또는 1d로 설정하면 각 조합을 UTC 버킷별로 나눕니다. 이때 각 행의 starting_at과 ending_at은 해당 버킷의 경계가 됩니다. 사용량이나 비용이 없는 버킷은 행을 생성하지 않습니다.
• 기본적으로 순위가 매겨집니다: 행은 전체 범위에 걸친 order_by 지표를 기준으로 정렬되며, 기본적으로 가장 큰 값이 먼저 옵니다(order=asc는 순서를 반대로 합니다). 시계열을 만들려면 time_bucket_width와 order_by=time을 설정하세요. 그러면 행이 시간 버킷 순서대로 반환되며, 기본적으로 가장 최근 버킷이 먼저 오고(order=asc는 가장 오래된 버킷을 먼저 둡니다) 각 버킷 내에서는 가장 큰 행이 먼저 옵니다. 빈 버킷은 0으로 채우세요.
• 필터는 그룹화와 함께 작동합니다: 그룹화할 수 있는 대부분의 차원에는 models[]=claude-opus-5-5와 같이 대괄호 표기법을 사용하는 대응 목록 필터가 있습니다. 여러 값을 전달하려면 매개변수를 반복하세요(최대 100개). 같은 필터의 여러 값은 OR로 결합되고, 서로 다른 필터는 AND로 결합됩니다. 필터와 group_by[]는 서로 독립적이므로, 어떤 차원으로든 그룹화 여부와 관계없이 필터링할 수 있으며 그 반대도 가능합니다.

model 및 actor와 같은 차원은 모든 조직에 적용됩니다. api_key_id와 같은 일부 차원은 Claude Console 조직에만 적용되고, slack_channel_id와 같은 다른 차원은 Claude Enterprise 조직에만 적용됩니다. 조직에 적용되지 않는 차원은 모든 행에서 null이며 해당 필터는 아무것도 일치시키지 않습니다. 예외는 rbac_group_id로, 조직에서 팀을 사용할 수 없는 경우 대신 오류를 반환합니다. 사용량 및 비용 API 레퍼런스에 모든 차원, 필터 및 값이 나열되어 있습니다.

액터

actor 차원은 요청이 귀속되는 대상입니다. 사용자, 서비스 계정, 페더레이션 클라우드 ID(클라우드 플랫폼을 통해 Claude에 액세스하는 조직의 경우 AWS 또는 Google Cloud 주체), 또는 요청의 주체가 이들 중 어느 것도 아닌 경우 API 키 자체입니다. actor로 그룹화하면 각 행의 actor는 type이 그 종류를 나타내는 객체입니다. 어떤 ID에도 귀속될 수 없는 사용량은 actor: null을 가집니다.

개인 키와 서비스 계정 키는 연결된 사용자 또는 서비스 계정으로 동작하므로, 해당 요청은 그 ID를 actor로, 키를 api_key_id로 표시합니다. 레거시 워크스페이스 키는 ID에 연결되어 있지 않으므로 키가 actor와 api_key_id 모두로 나타납니다. 예외는 멤버가 Claude Console 계정으로 로그인할 때 Claude Code가 생성하는 키입니다. 이 키는 Claude Code 워크스페이스에 있으며, 그 사용량은 해당 멤버에게 귀속됩니다. Claude Console에서 보낸 요청이나 Workload Identity Federation 토큰을 사용한 요청처럼 API 키 없이 보낸 요청은 api_key_id: null을 가집니다. 페더레이션 워크로드의 actor는 해당 서비스 계정입니다. API 키가 없는 사용량을 api_key_ids[] 필터에 포함하려면 빈 항목 api_key_ids[]=를 추가하세요.

api_key_ids[]와 actor_ids[] 필터는 서로 다른 질문에 답합니다. api_key_ids[]=apikey_...는 누구에게 귀속되든 해당 키가 인증한 모든 요청과 일치합니다. actor_ids[]=apikey_...는 키 자체에 귀속된 요청만 일치시킵니다.

사용량 엔드포인트

GET /v1/organizations/analytics/usage는 유형별 토큰 수를 반환합니다. order_by는 total_tokens(기본값), output_tokens, uncached_input_tokens, requests 또는 time을 받습니다.

예를 들어, 하나의 워크스페이스와 하나의 API 키에 대한 일주일간의 사용량을 서비스 티어별로 세분화하여 보려면(티어마다 한 행, 일주일 전체를 다룸) 다음과 같이 합니다:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    api_key_ids=["apikey_01Rj2N8SVvo6BePZj99NhmiT"],
    group_by=["service_tier"],
)

for row in rows:
    print(f"{row.group.service_tier}: {row.usage.total_tokens}")

API 키 및 워크스페이스 ID를 조회하려면 List API Keys 및 List Workspaces 엔드포인트 또는 Claude Console을 사용하세요.

한 달 동안 가장 많은 요청을 보낸 사용자, 서비스 계정 및 API 키를 찾으려면:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["actor"],
    order_by="requests",
    limit=25,
)

for row in rows:
    print(f"{row.group.actor}: {row.usage.requests}")

비용 엔드포인트

GET /v1/organizations/analytics/cost는 /usage 엔드포인트와 동일한 필터, 차원, 시간 버킷을 받습니다. 각 행의 cost 객체에는 amount(할인 적용 후, 크레딧 적용 전의 비용), list_amount(정가 기준 비용), currency(항상 "USD"), requests가 포함됩니다. 금액은 소수점 이하 여섯 자리의 센트 단위 십진수 문자열입니다. 예를 들어 "41280.000000"은 $412.80 USD입니다. order_by는 amount(기본값), list_amount 또는 time을 받습니다.

이 엔드포인트에만 존재하며 5개 차원 제한에 포함되지 않는 두 가지 추가 차원이 있습니다. group_by[]=cost_type은 각 행을 비용 유형마다 한 행으로 나누고, group_by[]=token_type은 토큰 비용을 토큰 유형마다 한 행으로 나눕니다. limit도 이 두 차원에는 적용되지 않으므로, 한 페이지에 limit보다 많은 행이 포함될 수 있습니다. 예를 들어, 한 달 동안의 모델, 비용 유형, 토큰 유형별 비용은 다음과 같습니다:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["model", "cost_type", "token_type"],
)

for row in rows:
    print(
        f"{row.group.model} {row.group.cost_type} {row.group.token_type}: {row.cost.amount}"
    )

각 모델에 대해 응답에는 5개의 tokens 행(토큰 유형마다 하나)과 web_search, code_execution, session_usage에 대한 행이 각각 하나씩 포함됩니다. 그중 한 행은 다음과 같습니다:

{
  "starting_at": "2026-09-01T00:00:00Z",
  "ending_at": "2026-10-01T00:00:00Z",
  "group": {
    "model": "claude-opus-5",
    ...,
    "cost_type": "tokens",
    "token_type": "cache_read_input_tokens"
  },
  "cost": {
    "currency": "USD",
    "amount": "41280.000000",
    "list_amount": "51600.000000",
    "requests": null
  }
}

group 객체는 모든 차원을 담고 있으며 여기서는 축약되어 있습니다. group_by[]=cost_type 또는 token_type을 지정하면 모든 행에서 requests는 null입니다.

날짜 범위와 시간 버킷

• 타임스탬프는 UTC 오프셋이 포함된 RFC 3339 형식입니다(예: 2026-09-01T00:00:00Z). starting_at은 포함되고 ending_at은 제외됩니다.
• starting_at은 2026년 1월 1일 이후이면서 최근 365일 이내여야 합니다. 하나의 요청은 최대 31일에 걸칠 수 있습니다. ending_at의 기본값은 starting_at으로부터 31일 후 또는 현재 시간 중 더 이른 시점입니다.
• time_bucket_width가 설정된 경우 ending_at은 필수이며, time_bucket_width=1m인 경우 하나의 요청은 최대 24시간에 걸칠 수 있습니다.
• 범위의 양 끝은 UTC 버킷 경계로 내림되며, time_bucket_width가 설정되지 않은 경우 시간 단위로 내림됩니다. 예를 들어 time_bucket_width=1h인 경우 2026-09-01T10:43:00Z의 starting_at은 2026-09-01T10:00:00Z로, 2026-09-01T15:43:00Z의 ending_at은 2026-09-01T15:00:00Z로 처리되므로 응답은 UTC 10:00부터 15:00까지를 포함합니다.

데이터 최신성

모든 응답에는 data_refreshed_at 타임스탬프가 포함되며, 그 시점 이후의 사용량은 누락되었거나 일부만 반영되어 있습니다. 요청한 범위의 어느 부분에 대해서도 아직 사용 가능한 데이터가 없으면 data_refreshed_at은 null이고 data는 비어 있습니다. 데이터는 일반적으로 기반 사용량 발생 후 4시간 이내에 갱신되며, 최대 24시간이 걸릴 수 있습니다. 늦게 도착하는 이벤트와 조정 작업에 따라 값은 해당 달력 월이 끝난 후 약 7일까지 수정될 수 있습니다. 예를 들어, 10월 1일의 값은 약 11월 7일까지 변경될 수 있습니다. 반복 호출에서 안정적인 결과를 얻으려면 ending_at을 이미 확인한 data_refreshed_at 시점 또는 그 이전으로 설정하세요. 최종 합계를 얻으려면 종료된 지 최소 7일이 지난 월만 쿼리하세요. 페이지네이션된 쿼리의 모든 페이지는 동일한 데이터 스냅샷을 읽으므로, data_refreshed_at은 모든 페이지에서 동일합니다.

Usage and Cost API에서 마이그레이션

이 섹션은 레거시 Usage and Cost API(/v1/organizations/usage_report/messages 및 /v1/organizations/cost_report)를 호출하는 Claude Console 조직을 위한 것입니다. Admin API 키, anthropic-version 헤더, starting_at 및 ending_at, 버킷 너비 값(1m, 1h, 1d), 대괄호 표기법, 페이지네이션 필드 이름, 토큰 및 비용 필드 이름은 그대로 유지됩니다. 변경 사항은 다음과 같습니다:

기존 일별 보고서를 재현하려면 동일한 group_by[]와 함께 time_bucket_width=1d를 요청하고, limit=1000으로 페이지를 넘기며 조회한 다음, 행을 starting_at별로 그룹화하고 누락된 날짜를 0으로 채우세요. 날짜를 순서대로 받으려면 order_by=time&order=asc를 추가하세요. 1주일간의 모델별 일일 사용량, 이전 방식:

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

이후:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=1000,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

워크스페이스, 모델, 서비스 티어, 컨텍스트 윈도우 및 추론 지역별 일별 비용을 비용 유형과 토큰 유형으로 나눈 예:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=[
        "workspace_id",
        "model",
        "service_tier",
        "context_window",
        "inference_geo",
        "cost_type",
        "token_type",
    ],
    limit=1000,
)

for row in rows:
    group = row.group
    print(
        f"{row.starting_at} {group.workspace_id} {group.model} {group.service_tier} "
        f"{group.context_window} {group.inference_geo} {group.cost_type} {group.token_type}: "
        f"{row.cost.amount}"
    )

Claude Enterprise 사용량 및 비용 보고서에서 마이그레이션

이 섹션은 /v1/organizations/analytics/ 아래의 Claude Enterprise Analytics API 보고서 엔드포인트 usage_report, cost_report, user_usage_report, user_cost_report를 호출하는 Claude Enterprise 조직을 위한 것입니다. 이러한 엔드포인트는 레거시이며 계속 지원됩니다. 다음 중 하나가 필요할 때 /analytics/usage 및 /analytics/cost로 이동하세요:

• 각 버킷의 상위 100개 그룹이 아닌, 모든 시간 버킷의 모든 그룹
• 사용량과 비용 모두에서 actor 또는 actor_type을 다른 차원과 함께 그룹화
• 전체 범위에 걸쳐 원하는 지표로 순위가 매겨지거나 시간 버킷별로 정렬된 행
• Claude Console 조직에도 제공되는 하나의 통합

키, 가장 이른 날짜, 365일 조회 기간과 31일 범위, 필터 및 차원 이름과 값(user_ids[]와 Claude Tag 제품 값 제외), 사용자 actor 필드, 지표 및 금액 필드, data_refreshed_at, 커서 규칙, 조직 수준 속도 제한은 그대로 유지됩니다. 새로 추가되는 헤더는 analytics-usage-cost-2026-08-24 베타 헤더뿐입니다. 변경 사항은 다음과 같습니다:

한 달 동안의 사용자별 비용, 이전:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.user_cost_report.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    limit=100,
)

for row in rows:
    print(f"{row.actor.user_id}: {row.amount}")

이후, 제품별 분류 추가:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    actor_types=["user_actor"],
    group_by=["actor", "product"],
    limit=100,
)

for row in rows:
    actor = row.group.actor
    if actor is not None and actor.type == "user_actor":
        print(f"{actor.user_id} {row.group.product}: {row.cost.amount}")

자주 묻는 질문

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

Claude Console 조직의 기본 워크스페이스는 다른 모든 워크스페이스와 마찬가지로 자체 wrkspc_ ID를 가집니다. 기본 워크스페이스에 대한 행의 workspace_id에는 해당 ID가 들어 있으며, workspace_ids[]로 이를 필터링할 수 있습니다. List Workspaces는 include_default=true를 전달하지 않는 한 기본 워크스페이스를 제외합니다. 익숙하지 않은 workspace_id가 기본 워크스페이스인지 확인하려면 Get Workspace에 전달하세요. 기본 워크스페이스는 "name": "Default"를 반환합니다.

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

products[]=claude_code&group_by[]=actor로 비용 엔드포인트를 호출하세요. Claude Console 조직은 사용자별 Claude Code 활동과 예상 비용을 보고하는 Claude Code Analytics API도 사용할 수 있습니다.

참고 항목

• Usage and Cost API(레거시)
• Analytics API: 조직에 필요한 분석 API 및 키 유형
• Claude Code Analytics API
• Admin API 레퍼런스
• 가격