--- title: Usage and Cost Analytics API url: https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api description: Claude Console 또는 Claude Enterprise 조직의 토큰 사용량과 비용을 모델, 워크스페이스, API 키, 액터 등을 기준으로 조회합니다. --- **Admin API는 개인 계정에서는 사용할 수 없습니다.** 팀원과 협업하고 멤버를 추가하려면 Claude Console의 [Organization](https://platform.claude.com/settings/organization) 페이지(`platform.claude.com/settings/organization`)에서 조직을 설정하세요. Usage and Cost Analytics API는 조직의 과거 토큰 사용량과 비용을 모델, 워크스페이스, API 키 또는 각 요청을 보낸 사용자나 서비스 계정 등 선택한 차원별로 나누어 보고합니다. Claude Console 조직의 경우 이 데이터는 Claude Console의 [Usage](https://platform.claude.com/usage) 및 [Cost](https://platform.claude.com/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`](https://platform.claude.com/docs/ko/api/versioning) 헤더를 보내세요. SDK와 `ant` CLI는 두 헤더를 자동으로 보내고 결과를 읽는 동안 나머지 페이지를 가져오므로, `limit`은 페이지 크기만 설정합니다. 이 API를 사용하여 다음을 수행할 수 있습니다: * **지출 귀속:** 워크스페이스, API 키, 모델, 서비스 티어 또는 각 요청을 보낸 ID별로 비용과 토큰 사용량을 세분화합니다. * **상위 소비자 찾기:** 토큰, 요청 또는 비용을 기준으로 결과의 순위를 매겨 "이번 달에 가장 많이 지출한 API 키는 무엇인가?"와 같은 질문에 답합니다. * **시계열 구축:** 대시보드와 재무 보고서를 위해 결과를 일별, 시간별 또는 분별 버킷으로 나눕니다. * **한 번의 통합:** 동일한 엔드포인트, 매개변수, 응답 필드가 Claude Console 조직과 Claude Enterprise 조직 모두에 제공됩니다. **Admin API 키 필요** Claude Console 조직은 [Admin API 키](https://platform.claude.com/docs/ko/manage-claude/admin-api-keys#create-a-key-for-a-claude-console-organization) 또는 다른 [Admin API 자격 증명](https://platform.claude.com/docs/ko/manage-claude/admin-api#authentication)을 사용합니다. Claude Enterprise 조직은 조직에 Analytics API가 활성화된 후 기본 소유자가 claude.ai에서 생성한 `read:analytics` 범위의 키를 사용합니다. [Claude Enterprise Analytics API 액세스 얻기](https://platform.claude.com/docs/ko/manage-claude/analytics-api#get-access-to-the-claude-enterprise-analytics-api)를 참조하세요. 어느 경우든 `ANTHROPIC_API_KEY` 환경 변수를 해당 키로 설정하세요. 이 페이지의 예제는 이 환경 변수에서 키를 읽습니다. Admin API 키로 이러한 엔드포인트를 호출하는 경우, 이 데이터를 수집하는 서비스에 전용 키를 부여하고, 시크릿 관리자에 저장하며, 정기적으로 교체하세요. 키를 생성할 때 [키 만료](https://platform.claude.com/docs/ko/manage-claude/authentication#key-expiration)를 설정하면 교체가 강제됩니다. 가능하다면 대신 [`org:admin` 범위](https://platform.claude.com/docs/ko/manage-claude/wif-reference#oauth-scopes)를 가진 [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation) 규칙을 사용하세요. 그러면 서비스가 수명이 짧은 토큰을 받으므로 유출될 수 있는 장기 키가 없습니다. **Claude Platform on AWS:** 두 엔드포인트 모두 사용할 수 있습니다. 요청은 Admin API 키 대신 Claude Platform on AWS 기본 URL과 인증을 사용하며([요청 보내기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#making-requests) 참조), AWS IAM이 [`ListAccountUsage` 및 `ListAccountCost` 작업](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#usage-and-cost)을 통해 요청을 승인합니다. 각 요청은 호출하는 엔드포인트의 AWS 리전에 있는 워크스페이스만 다루므로, 조직 전체를 다루려면 각 리전의 엔드포인트를 호출하세요. `user_profile_id`, `claude_tag_category`, `claude_tag_user_id` 및 Claude Managed Agents 차원(`agent_id`, `environment_id`, `deployment_id`, `session_id`)은 모든 행에서 `null`입니다. **Claude Models on Google Cloud (Anthropic managed):** 두 엔드포인트 모두 사용할 수 있습니다. Admin API 키 대신 Google Cloud 자격 증명을 사용하여 [조직 수준 기본 URL](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed#making-requests)을 통해 호출하세요. `/usage` 엔드포인트에는 `usageAnalytics.list` [IAM 권한](https://platform.claude.com/docs/ko/api/claude-models-on-google-cloud-anthropic-managed-iam-permissions)이 필요하며, `/cost` 엔드포인트에는 `costAnalytics.list`가 필요합니다. ## 빠른 시작 9월 첫째 주의 일별 토큰 사용량을 모델과 날짜별로 한 행씩 가져옵니다: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-09-08T00:00:00Z&\ time_bucket_width=1d&\ group_by[]=model&\ limit=10" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant 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 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log(`${row.starting_at} ${row.group.model}: ${row.usage.total_tokens}`); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics; using Anthropic.Models.Beta.Organization.Analytics.Usage; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Usage.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-09-08T00:00:00Z"), TimeBucketWidth = BetaAnalyticsTimeBucketWidth.Day, GroupBy = [BetaAnalyticsUsageGroupBy.Model], Limit = 10, } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.StartingAt} {row.Group.Model}: {row.Usage.TotalTokens}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Usage.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUsageListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.September, 8, 0, 0, 0, 0, time.UTC)), TimeBucketWidth: anthropic.BetaAnalyticsTimeBucketWidthDay, GroupBy: []anthropic.BetaAnalyticsUsageGroupBy{anthropic.BetaAnalyticsUsageGroupByModel}, Limit: anthropic.Int(10), }) for rows.Next() { row := rows.Current() fmt.Printf("%s %s: %d\n", row.StartingAt.Format(time.RFC3339), row.Group.Model, row.Usage.TotalTokens) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.BetaAnalyticsTimeBucketWidth; import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageGroupBy; import com.anthropic.models.beta.organization.analytics.usage.UsageListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UsageListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-09-08T00:00:00Z")) .timeBucketWidth(BetaAnalyticsTimeBucketWidth.DAY) .addGroupBy(BetaAnalyticsUsageGroupBy.MODEL) .limit(10) .build(); var rows = client.beta().organization().analytics().usage().list(params); for (var row : rows.autoPager()) { IO.println(row.startingAt() + " " + row.group().model().orElse(null) + ": " + row.usage().totalTokens()); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-09-08T00:00:00Z'), timeBucketWidth: '1d', groupBy: ['model'], limit: 10, ); foreach ($rows->pagingEachItem() as $row) { $startingAt = $row->startingAt->format(\DateTimeInterface::ATOM); echo "{$startingAt} {$row->group->model}: {$row->usage->totalTokens}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.usage.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 9, 8), time_bucket_width: :"1d", group_by: [:model], limit: 10 ) page.auto_paging_each do |row| puts "#{row.starting_at} #{row.group.model}: #{row.usage.total_tokens}" end ``` 응답에는 사용량이 있는 모델과 날짜마다 한 행이 포함되며, `total_tokens`가 가장 큰 행이 먼저 나옵니다. 이 예시는 단일 행을 보여줍니다: ```json { "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" } ``` **통합을 위한 User-Agent 헤더 설정** 통합을 구축하는 경우, Anthropic이 사용 패턴을 이해할 수 있도록 User-Agent 헤더를 설정하세요: ```text wrap User-Agent: YourApp/1.0.0 (https://yourapp.com) ``` ## 결과의 구성 방식 * **모든 행은 세 부분으로 구성됩니다:** `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`로, 조직에서 팀을 사용할 수 없는 경우 대신 오류를 반환합니다. [사용량](https://platform.claude.com/docs/ko/api/beta/organization/analytics/usage/list) 및 [비용](https://platform.claude.com/docs/ko/api/beta/organization/analytics/cost/list) API 레퍼런스에 모든 차원, 필터 및 값이 나열되어 있습니다. ### 액터 `actor` 차원은 요청이 귀속되는 대상입니다. 사용자, 서비스 계정, 페더레이션 클라우드 ID(클라우드 플랫폼을 통해 Claude에 액세스하는 조직의 경우 AWS 또는 Google Cloud 주체), 또는 요청의 주체가 이들 중 어느 것도 아닌 경우 API 키 자체입니다. `actor`로 그룹화하면 각 행의 `actor`는 `type`이 그 종류를 나타내는 객체입니다. 어떤 ID에도 귀속될 수 없는 사용량은 `actor: null`을 가집니다. [개인 키와 서비스 계정 키](https://platform.claude.com/docs/ko/manage-claude/authentication#key-types)는 연결된 사용자 또는 서비스 계정으로 동작하므로, 해당 요청은 그 ID를 `actor`로, 키를 `api_key_id`로 표시합니다. 레거시 워크스페이스 키는 ID에 연결되어 있지 않으므로 키가 `actor`와 `api_key_id` 모두로 나타납니다. 예외는 멤버가 Claude Console 계정으로 로그인할 때 Claude Code가 생성하는 키입니다. 이 키는 [Claude Code 워크스페이스](https://platform.claude.com/docs/ko/manage-claude/workspaces#claude-code-workspace)에 있으며, 그 사용량은 해당 멤버에게 귀속됩니다. Claude Console에서 보낸 요청이나 [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/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 키에 대한 일주일간의 사용량을 서비스 티어별로 세분화하여 보려면(티어마다 한 행, 일주일 전체를 다룸) 다음과 같이 합니다: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\ 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" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant beta:organization:analytics:usage list \ --starting-at 2026-09-01T00:00:00Z \ --ending-at 2026-09-08T00:00:00Z \ --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \ --api-key-id apikey_01Rj2N8SVvo6BePZj99NhmiT \ --group-by service_tier ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log(`${row.group.service_tier}: ${row.usage.total_tokens}`); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics.Usage; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Usage.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-09-08T00:00:00Z"), WorkspaceIds = ["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"], ApiKeyIds = ["apikey_01Rj2N8SVvo6BePZj99NhmiT"], GroupBy = [BetaAnalyticsUsageGroupBy.ServiceTier], } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.Group.ServiceTier?.Raw()}: {row.Usage.TotalTokens}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Usage.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUsageListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.September, 8, 0, 0, 0, 0, time.UTC)), WorkspaceIDs: []string{"wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"}, APIKeyIDs: []string{"apikey_01Rj2N8SVvo6BePZj99NhmiT"}, GroupBy: []anthropic.BetaAnalyticsUsageGroupBy{anthropic.BetaAnalyticsUsageGroupByServiceTier}, }) for rows.Next() { row := rows.Current() fmt.Printf("%s: %d\n", row.Group.ServiceTier, row.Usage.TotalTokens) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageGroupBy; import com.anthropic.models.beta.organization.analytics.usage.UsageListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UsageListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-09-08T00:00:00Z")) .addWorkspaceId("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ") .addApiKeyId("apikey_01Rj2N8SVvo6BePZj99NhmiT") .addGroupBy(BetaAnalyticsUsageGroupBy.SERVICE_TIER) .build(); var rows = client.beta().organization().analytics().usage().list(params); for (var row : rows.autoPager()) { IO.println(row.group().serviceTier().orElse(null) + ": " + row.usage().totalTokens()); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-09-08T00:00:00Z'), workspaceIDs: ['wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'], apiKeyIDs: ['apikey_01Rj2N8SVvo6BePZj99NhmiT'], groupBy: ['service_tier'], ); foreach ($rows->pagingEachItem() as $row) { echo "{$row->group->serviceTier}: {$row->usage->totalTokens}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.usage.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 9, 8), workspace_ids: ["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"], api_key_ids: ["apikey_01Rj2N8SVvo6BePZj99NhmiT"], group_by: [:service_tier] ) page.auto_paging_each do |row| puts "#{row.group.service_tier}: #{row.usage.total_tokens}" end ``` API 키 및 워크스페이스 ID를 조회하려면 [List API Keys](https://platform.claude.com/docs/ko/api/organization/api_keys/list) 및 [List Workspaces](https://platform.claude.com/docs/ko/api/organization/workspaces/list) 엔드포인트 또는 Claude Console을 사용하세요. 한 달 동안 가장 많은 요청을 보낸 사용자, 서비스 계정 및 API 키를 찾으려면: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-10-01T00:00:00Z&\ group_by[]=actor&\ order_by=requests&\ limit=25" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant 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 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log(`${JSON.stringify(row.group.actor)}: ${row.usage.requests}`); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics.Usage; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Usage.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-10-01T00:00:00Z"), GroupBy = [BetaAnalyticsUsageGroupBy.Actor], OrderBy = BetaAnalyticsUsageOrderBy.Requests, Limit = 25, } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.Group.Actor?.Json}: {row.Usage.Requests}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Usage.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUsageListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.October, 1, 0, 0, 0, 0, time.UTC)), GroupBy: []anthropic.BetaAnalyticsUsageGroupBy{anthropic.BetaAnalyticsUsageGroupByActor}, OrderBy: anthropic.BetaAnalyticsUsageOrderByRequests, Limit: anthropic.Int(25), }) for rows.Next() { row := rows.Current() fmt.Printf("%s: %d\n", row.Group.Actor.RawJSON(), row.Usage.Requests) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageGroupBy; import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageOrderBy; import com.anthropic.models.beta.organization.analytics.usage.UsageListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UsageListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-10-01T00:00:00Z")) .addGroupBy(BetaAnalyticsUsageGroupBy.ACTOR) .orderBy(BetaAnalyticsUsageOrderBy.REQUESTS) .limit(25) .build(); var rows = client.beta().organization().analytics().usage().list(params); for (var row : rows.autoPager()) { IO.println(row.group().actor().orElse(null) + ": " + row.usage().requests().orElse(null)); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), groupBy: ['actor'], orderBy: 'requests', limit: 25, ); foreach ($rows->pagingEachItem() as $row) { $actor = json_encode($row->group->actor); echo "{$actor}: {$row->usage->requests}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.usage.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 10, 1), group_by: [:actor], order_by: :requests, limit: 25 ) page.auto_paging_each do |row| puts "#{row.group.actor}: #{row.usage.requests}" end ``` ## 비용 엔드포인트 `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`보다 많은 행이 포함될 수 있습니다. 예를 들어, 한 달 동안의 모델, 비용 유형, 토큰 유형별 비용은 다음과 같습니다: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/cost?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-10-01T00:00:00Z&\ group_by[]=model&\ group_by[]=cost_type&\ group_by[]=token_type" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant beta:organization:analytics:cost list \ --starting-at 2026-09-01T00:00:00Z \ --ending-at 2026-10-01T00:00:00Z \ --group-by model \ --group-by cost_type \ --group-by token_type ``` ```python Python 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}" ) ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log( `${row.group.model} ${row.group.cost_type} ${row.group.token_type}: ${row.cost.amount}` ); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics.Cost; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Cost.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-10-01T00:00:00Z"), GroupBy = [BetaAnalyticsCostGroupBy.Model, BetaAnalyticsCostGroupBy.CostType, BetaAnalyticsCostGroupBy.TokenType], } ); await foreach (var row in page.Paginate()) { Console.WriteLine( $"{row.Group.Model} {row.Group.CostType?.Raw()} {row.Group.TokenType?.Raw()}: {row.Cost.Amount}" ); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Cost.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsCostListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.October, 1, 0, 0, 0, 0, time.UTC)), GroupBy: []anthropic.BetaAnalyticsCostGroupBy{anthropic.BetaAnalyticsCostGroupByModel, anthropic.BetaAnalyticsCostGroupByCostType, anthropic.BetaAnalyticsCostGroupByTokenType}, }) for rows.Next() { row := rows.Current() fmt.Printf("%s %s %s: %s\n", row.Group.Model, row.Group.CostType, row.Group.TokenType, row.Cost.Amount) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.cost.BetaAnalyticsCostGroupBy; import com.anthropic.models.beta.organization.analytics.cost.CostListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = CostListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-10-01T00:00:00Z")) .addGroupBy(BetaAnalyticsCostGroupBy.MODEL) .addGroupBy(BetaAnalyticsCostGroupBy.COST_TYPE) .addGroupBy(BetaAnalyticsCostGroupBy.TOKEN_TYPE) .build(); var rows = client.beta().organization().analytics().cost().list(params); for (var row : rows.autoPager()) { var group = row.group(); IO.println( group.model().orElse(null) + " " + group.costType().orElse(null) + " " + group.tokenType().orElse(null) + ": " + row.cost().amount() ); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->cost->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), groupBy: ['model', 'cost_type', 'token_type'], ); foreach ($rows->pagingEachItem() as $row) { $group = $row->group; echo "{$group->model} {$group->costType} {$group->tokenType}: {$row->cost->amount}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.cost.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 10, 1), group_by: [:model, :cost_type, :token_type] ) page.auto_paging_each do |row| group = row.group puts "#{group.model} #{group.cost_type} #{group.token_type}: #{row.cost.amount}" end ``` 각 모델에 대해 응답에는 5개의 `tokens` 행(토큰 유형마다 하나)과 `web_search`, `code_execution`, `session_usage`에 대한 행이 각각 하나씩 포함됩니다. 그중 한 행은 다음과 같습니다: ```json { "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`입니다. Priority Tier 약정에 따라 처리된 요청은 사용량 엔드포인트에 `service_tier: "priority"`로 나타나지만, 약정이 이를 포함하므로 `amount` 및 `list_amount`에서 토큰 비용이 0으로 집계됩니다. 약정 요금은 별도로 청구되며 이 데이터에 포함되지 않습니다. 해당 요청의 웹 검색은 표준 요금으로 청구됩니다. 약정 용량을 초과하는 요청은 표준 티어로 처리되고 가격이 책정됩니다. ## 날짜 범위와 시간 버킷 * 타임스탬프는 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](https://platform.claude.com/docs/ko/manage-claude/usage-cost-api)(`/v1/organizations/usage_report/messages` 및 `/v1/organizations/cost_report`)를 호출하는 Claude Console 조직을 위한 것입니다. Admin API 키, `anthropic-version` 헤더, `starting_at` 및 `ending_at`, 버킷 너비 값(`1m`, `1h`, `1d`), 대괄호 표기법, 페이지네이션 필드 이름, 토큰 및 비용 필드 이름은 그대로 유지됩니다. 변경 사항은 다음과 같습니다: | Usage and Cost API | Usage and Cost Analytics API | | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 베타 헤더 없음 | 모든 요청에 `anthropic-beta: analytics-usage-cost-2026-08-24` | | 데이터는 일반적으로 5분 이내에 표시됨 | 데이터는 일반적으로 4시간 이내에 갱신되며 최대 24시간이 걸릴 수 있음([데이터 최신성](https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api#data-freshness) 참조) | | `data`는 빈 버킷을 포함하여 오래된 순으로 정렬된 시간 버킷 목록이며, 각 버킷에는 차원과 지표를 나란히 담은 항목들로 구성된 `results` 목록이 있음 | `data`는 `order_by` 기준으로 순위가 매겨진 행 목록이며, 각 행에는 자체 `starting_at`과 `ending_at`, `group`의 차원, `usage` 또는 `cost`의 지표가 있음. 사용량이나 비용이 없는 조합에는 행이 없음. | | `bucket_width`, 기본값 `1d` | `time_bucket_width`, 기본값 없음. 일별 행을 유지하려면 `time_bucket_width=1d`를 전달하고, 전체 범위 합계를 원하면 생략하세요. 비용 엔드포인트도 모든 필터와 `1m` 및 `1h` 버킷을 허용함. | | `limit`은 페이지당 시간 버킷 수를 셈 | `limit`은 페이지당 행 수를 셈(1\~1,000, 기본값 20). 따라서 페이지 수는 데이터가 있는 조합의 수에 따라 달라짐 | | 모든 날짜 범위, 버킷 단위로 앞으로 페이지 이동 | `starting_at`은 2026년 1월 1일 이후이면서 최근 365일 이내여야 하고, 요청당 최대 31일, `time_bucket_width` 사용 시 `ending_at` 필수, `1m` 버킷은 최대 24시간([날짜 범위와 시간 버킷](https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api#date-ranges-and-time-buckets) 참조). 더 긴 범위는 여러 요청으로 나누세요. | | `account_ids[]`, `service_account_ids[]`, `group_by[]=account_id`, `group_by[]=service_account_id` | 동일한 태그 ID를 사용하는 `actor_ids[]`와 `group_by[]=actor` 또는 `actor_type`. `actor.user_id` 또는 `actor.service_account_id`를 읽으세요. [액터](https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api#actors)를 참조하세요. | | `context_window[]` | `context_windows[]` | | 비용 보고서의 `group_by[]=description`과 `description` 문자열 | `description` 없음. 대신 구조화된 차원으로 그룹화하세요: `model`, `cost_type`, `token_type`, `context_window`, `service_tier`, `inference_geo`, `speed` 중 어느 것이든 사용할 수 있으며, 모두 한 요청에 담을 수 있음. | | 알 수 없는 API 키 또는 워크스페이스 ID는 오류를 반환함 | 아무것도 일치하지 않음. 철자가 틀린 `models[]` 이름도 마찬가지임. 각 목록은 최대 100개의 값을 받음. | | 기본 워크스페이스의 경우 `workspace_id: null` | 기본 워크스페이스의 실제 `workspace_id`([기본 워크스페이스는 어떻게 표현되나요?](https://platform.claude.com/docs/ko/manage-claude/usage-cost-analytics-api#how-is-the-default-workspace-represented) 참조) | | 지역이나 티어가 없는 사용량에 `inference_geo: "not_available"` 및 `service_tier: "standard"` | 둘 다 `null`. `inference_geos[]=not_available`은 여전히 추론 지역이 없는 행과 일치함. | | 비용 `service_tier`는 `standard` 또는 `batch`, `amount`는 `"123.45"`와 같은 형식 | 실제 티어. `amount`는 `"123.450000"`과 같이 소수점 이하 6자리이며, `list_amount`가 추가됨. | | 코드 실행은 사용량 보고서에 없음, 요청 수 없음 | 코드 실행은 `model: null`인 사용량 행으로 나타남. 두 엔드포인트 모두에 `requests`가 추가되고 사용량 행에 `total_tokens`가 추가됨 | 기존 일별 보고서를 재현하려면 동일한 `group_by[]`와 함께 `time_bucket_width=1d`를 요청하고, `limit=1000`으로 페이지를 넘기며 조회한 다음, 행을 `starting_at`별로 그룹화하고 누락된 날짜를 0으로 채우세요. 날짜를 순서대로 받으려면 `order_by=time&order=asc`를 추가하세요. 1주일간의 모델별 일일 사용량, 이전 방식: ```bash cURL 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" ``` 이후: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-09-08T00:00:00Z&\ group_by[]=model&\ time_bucket_width=1d&\ limit=1000" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant 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 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log(`${row.starting_at} ${row.group.model}: ${row.usage.total_tokens}`); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics; using Anthropic.Models.Beta.Organization.Analytics.Usage; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Usage.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-09-08T00:00:00Z"), TimeBucketWidth = BetaAnalyticsTimeBucketWidth.Day, GroupBy = [BetaAnalyticsUsageGroupBy.Model], Limit = 1000, } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.StartingAt} {row.Group.Model}: {row.Usage.TotalTokens}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Usage.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUsageListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.September, 8, 0, 0, 0, 0, time.UTC)), TimeBucketWidth: anthropic.BetaAnalyticsTimeBucketWidthDay, GroupBy: []anthropic.BetaAnalyticsUsageGroupBy{anthropic.BetaAnalyticsUsageGroupByModel}, Limit: anthropic.Int(1000), }) for rows.Next() { row := rows.Current() fmt.Printf("%s %s: %d\n", row.StartingAt.Format(time.RFC3339), row.Group.Model, row.Usage.TotalTokens) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.BetaAnalyticsTimeBucketWidth; import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageGroupBy; import com.anthropic.models.beta.organization.analytics.usage.UsageListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UsageListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-09-08T00:00:00Z")) .timeBucketWidth(BetaAnalyticsTimeBucketWidth.DAY) .addGroupBy(BetaAnalyticsUsageGroupBy.MODEL) .limit(1000) .build(); var rows = client.beta().organization().analytics().usage().list(params); for (var row : rows.autoPager()) { IO.println(row.startingAt() + " " + row.group().model().orElse(null) + ": " + row.usage().totalTokens()); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-09-08T00:00:00Z'), timeBucketWidth: '1d', groupBy: ['model'], limit: 1000, ); foreach ($rows->pagingEachItem() as $row) { $startingAt = $row->startingAt->format(\DateTimeInterface::ATOM); echo "{$startingAt} {$row->group->model}: {$row->usage->totalTokens}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.usage.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 9, 8), time_bucket_width: :"1d", group_by: [:model], limit: 1000 ) page.auto_paging_each do |row| puts "#{row.starting_at} #{row.group.model}: #{row.usage.total_tokens}" end ``` 워크스페이스, 모델, 서비스 티어, 컨텍스트 윈도우 및 추론 지역별 일별 비용을 비용 유형과 토큰 유형으로 나눈 예: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/cost?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-09-08T00:00:00Z&\ time_bucket_width=1d&\ group_by[]=workspace_id&\ group_by[]=model&\ group_by[]=service_tier&\ group_by[]=context_window&\ group_by[]=inference_geo&\ group_by[]=cost_type&\ group_by[]=token_type&\ limit=1000" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant 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 \ --group-by model \ --group-by service_tier \ --group-by context_window \ --group-by inference_geo \ --group-by cost_type \ --group-by token_type \ --limit 1000 ``` ```python Python 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}" ) ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { const { group } = row; console.log( `${row.starting_at} ${group.workspace_id} ${group.model} ${group.service_tier} ` + `${group.context_window} ${group.inference_geo} ${group.cost_type} ${group.token_type}: ` + `${row.cost.amount}` ); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics; using Anthropic.Models.Beta.Organization.Analytics.Cost; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Cost.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-09-08T00:00:00Z"), TimeBucketWidth = BetaAnalyticsTimeBucketWidth.Day, GroupBy = [ BetaAnalyticsCostGroupBy.WorkspaceID, BetaAnalyticsCostGroupBy.Model, BetaAnalyticsCostGroupBy.ServiceTier, BetaAnalyticsCostGroupBy.ContextWindow, BetaAnalyticsCostGroupBy.InferenceGeo, BetaAnalyticsCostGroupBy.CostType, BetaAnalyticsCostGroupBy.TokenType, ], Limit = 1000, } ); await foreach (var row in page.Paginate()) { var group = row.Group; Console.WriteLine( $"{row.StartingAt} {group.WorkspaceID} {group.Model} {group.ServiceTier?.Raw()} " + $"{group.ContextWindow?.Raw()} {group.InferenceGeo?.Raw()} {group.CostType?.Raw()} " + $"{group.TokenType?.Raw()}: {row.Cost.Amount}" ); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Cost.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsCostListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.September, 8, 0, 0, 0, 0, time.UTC)), TimeBucketWidth: anthropic.BetaAnalyticsTimeBucketWidthDay, GroupBy: []anthropic.BetaAnalyticsCostGroupBy{ anthropic.BetaAnalyticsCostGroupByWorkspaceID, anthropic.BetaAnalyticsCostGroupByModel, anthropic.BetaAnalyticsCostGroupByServiceTier, anthropic.BetaAnalyticsCostGroupByContextWindow, anthropic.BetaAnalyticsCostGroupByInferenceGeo, anthropic.BetaAnalyticsCostGroupByCostType, anthropic.BetaAnalyticsCostGroupByTokenType, }, Limit: anthropic.Int(1000), }) for rows.Next() { row := rows.Current() group := row.Group fmt.Printf("%s %s %s %s %s %s %s %s: %s\n", row.StartingAt.Format(time.RFC3339), group.WorkspaceID, group.Model, group.ServiceTier, group.ContextWindow, group.InferenceGeo, group.CostType, group.TokenType, row.Cost.Amount) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.BetaAnalyticsTimeBucketWidth; import com.anthropic.models.beta.organization.analytics.cost.BetaAnalyticsCostGroupBy; import com.anthropic.models.beta.organization.analytics.cost.CostListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = CostListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-09-08T00:00:00Z")) .timeBucketWidth(BetaAnalyticsTimeBucketWidth.DAY) .addGroupBy(BetaAnalyticsCostGroupBy.WORKSPACE_ID) .addGroupBy(BetaAnalyticsCostGroupBy.MODEL) .addGroupBy(BetaAnalyticsCostGroupBy.SERVICE_TIER) .addGroupBy(BetaAnalyticsCostGroupBy.CONTEXT_WINDOW) .addGroupBy(BetaAnalyticsCostGroupBy.INFERENCE_GEO) .addGroupBy(BetaAnalyticsCostGroupBy.COST_TYPE) .addGroupBy(BetaAnalyticsCostGroupBy.TOKEN_TYPE) .limit(1000) .build(); var rows = client.beta().organization().analytics().cost().list(params); for (var row : rows.autoPager()) { var group = row.group(); IO.println( row.startingAt() + " " + group.workspaceId().orElse(null) + " " + group.model().orElse(null) + " " + group.serviceTier().orElse(null) + " " + group.contextWindow().orElse(null) + " " + group.inferenceGeo().orElse(null) + " " + group.costType().orElse(null) + " " + group.tokenType().orElse(null) + ": " + row.cost().amount() ); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->cost->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-09-08T00:00:00Z'), timeBucketWidth: '1d', groupBy: [ 'workspace_id', 'model', 'service_tier', 'context_window', 'inference_geo', 'cost_type', 'token_type', ], limit: 1000, ); foreach ($rows->pagingEachItem() as $row) { $startingAt = $row->startingAt->format(\DateTimeInterface::ATOM); $group = $row->group; echo "{$startingAt} {$group->workspaceID} {$group->model} {$group->serviceTier} " . "{$group->contextWindow} {$group->inferenceGeo} {$group->costType} {$group->tokenType}: " . "{$row->cost->amount}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.cost.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 9, 8), time_bucket_width: :"1d", group_by: [ :workspace_id, :model, :service_tier, :context_window, :inference_geo, :cost_type, :token_type ], limit: 1000 ) page.auto_paging_each do |row| group = row.group puts "#{row.starting_at} #{group.workspace_id} #{group.model} #{group.service_tier} " \ "#{group.context_window} #{group.inference_geo} #{group.cost_type} #{group.token_type}: " \ "#{row.cost.amount}" end ``` ## Claude Enterprise 사용량 및 비용 보고서에서 마이그레이션 이 섹션은 `/v1/organizations/analytics/` 아래의 [Claude Enterprise Analytics API](https://platform.claude.com/docs/ko/manage-claude/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`, 커서 규칙, [조직 수준 속도 제한](https://platform.claude.com/docs/ko/manage-claude/analytics-api#working-with-the-api)은 그대로 유지됩니다. 새로 추가되는 헤더는 `analytics-usage-cost-2026-08-24` 베타 헤더뿐입니다. 변경 사항은 다음과 같습니다: | Claude Enterprise 보고서 | Usage and Cost Analytics API | | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `usage_report`와 `cost_report`는 빈 버킷을 포함하여 오래된 순으로 시간 버킷을 반환하며, 각 버킷은 최대 상위 100개 그룹을 담음. `bucket_width`의 기본값은 `1d`이고 `limit`은 버킷 수를 셈 | 데이터가 있는 모든 조합을 다루는 행이 `order_by` 기준으로 순위가 매겨지며, 각 행에는 자체 `starting_at`과 `ending_at`, `group`의 차원, `usage` 또는 `cost`의 지표가 있음. `time_bucket_width`는 선택 사항이며 `limit`은 행 수를 셈. | | 시간 버킷 매개변수는 `bucket_width` | `time_bucket_width`이며, 값은 동일함 | | `usage_report`와 `cost_report`에서는 `bucket_width` 사용 시 `ending_at`이 선택 사항이며 `1m` 버킷은 최대 31일까지 가능 | `time_bucket_width` 사용 시 `ending_at` 필수. `1m` 버킷은 요청당 최대 24시간 | | `user_usage_report`와 `user_cost_report`는 사용자당 한 행을 반환함 | `group_by[]=actor&actor_types[]=user_actor`. 필터가 없으면 사용자가 아닌 ID에 대한 행과 귀속되지 않은 사용량에 대한 `actor: null` 행도 함께 반환됨. | | Claude Tag 사용량은 `product: "claude-tag"` | `product: "claude_tag"`. `products[]`는 두 철자 모두 허용함 | | 인식되지 않는 `models[]` 이름은 400 오류를 반환함 | 아무것도 일치하지 않음 | | `user_ids[]` | 동일한 태그 `user_...` ID를 사용하는 `actor_ids[]` | | 사용자별 보고서의 `exclude_deleted_users` | `group_by[]=actor`가 필요하며, 없으면 요청이 400 오류를 반환함. `actor`가 `deleted: true`인 사용자인 행만 제외하며, 다른 ID에 대한 행과 `actor: null`인 행은 유지됨. | 한 달 동안의 사용자별 비용, 이전: ```bash cURL curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-10-01T00:00:00Z&\ limit=100" \ -H "anthropic-version: 2023-06-01" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant beta:organization:analytics:user-cost-report list \ --starting-at 2026-09-01T00:00:00Z \ --ending-at 2026-10-01T00:00:00Z \ --limit 100 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await client.beta.organization.analytics.userCostReport.list({ starting_at: "2026-09-01T00:00:00Z", ending_at: "2026-10-01T00:00:00Z", limit: 100 }); for await (const row of rows) { console.log(`${row.actor.user_id}: ${row.amount}`); } ``` ```csharp C# AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.UserCostReport.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-10-01T00:00:00Z"), Limit = 100, } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.Actor.UserID}: {row.Amount}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.UserCostReport.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUserCostReportListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.October, 1, 0, 0, 0, 0, time.UTC)), Limit: anthropic.Int(100), }) for rows.Next() { row := rows.Current() fmt.Printf("%s: %s\n", row.Actor.UserID, row.Amount) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.usercostreport.UserCostReportListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UserCostReportListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-10-01T00:00:00Z")) .limit(100) .build(); var rows = client.beta().organization().analytics().userCostReport().list(params); for (var row : rows.autoPager()) { IO.println(row.actor().userId() + ": " + row.amount()); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->userCostReport->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), limit: 100, ); foreach ($rows->pagingEachItem() as $row) { echo "{$row->actor->userID}: {$row->amount}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.user_cost_report.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 10, 1), limit: 100 ) page.auto_paging_each do |row| puts "#{row.actor.user_id}: #{row.amount}" end ``` 이후, 제품별 분류 추가: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/cost?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-10-01T00:00:00Z&\ group_by[]=actor&\ group_by[]=product&\ actor_types[]=user_actor&\ limit=100" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant beta:organization:analytics:cost list \ --starting-at 2026-09-01T00:00:00Z \ --ending-at 2026-10-01T00:00:00Z \ --actor-type user_actor \ --group-by actor \ --group-by product \ --limit 100 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { const { actor } = row.group; if (actor?.type === "user_actor") { console.log(`${actor.user_id} ${row.group.product}: ${row.cost.amount}`); } } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics; using Anthropic.Models.Beta.Organization.Analytics.Cost; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Cost.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-10-01T00:00:00Z"), ActorTypes = [BetaAnalyticsActorType.UserActor], GroupBy = [BetaAnalyticsCostGroupBy.Actor, BetaAnalyticsCostGroupBy.Product], Limit = 100, } ); await foreach (var row in page.Paginate()) { if (row.Group.Actor is { } actor && actor.TryPickReportUser(out var user)) { Console.WriteLine($"{user.UserID} {row.Group.Product}: {row.Cost.Amount}"); } } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Cost.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsCostListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.October, 1, 0, 0, 0, 0, time.UTC)), ActorTypes: []anthropic.BetaAnalyticsActorType{anthropic.BetaAnalyticsActorTypeUserActor}, GroupBy: []anthropic.BetaAnalyticsCostGroupBy{anthropic.BetaAnalyticsCostGroupByActor, anthropic.BetaAnalyticsCostGroupByProduct}, Limit: anthropic.Int(100), }) for rows.Next() { row := rows.Current() if user, ok := row.Group.Actor.AsAny().(anthropic.BetaAnalyticsReportUserActor); ok { fmt.Printf("%s %s: %s\n", user.UserID, row.Group.Product, row.Cost.Amount) } } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.BetaAnalyticsActorType; import com.anthropic.models.beta.organization.analytics.cost.BetaAnalyticsCostGroupBy; import com.anthropic.models.beta.organization.analytics.cost.CostListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = CostListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-10-01T00:00:00Z")) .addActorType(BetaAnalyticsActorType.USER_ACTOR) .addGroupBy(BetaAnalyticsCostGroupBy.ACTOR) .addGroupBy(BetaAnalyticsCostGroupBy.PRODUCT) .limit(100) .build(); var rows = client.beta().organization().analytics().cost().list(params); for (var row : rows.autoPager()) { row.group().actor().flatMap(actor -> actor.user()).ifPresent(user -> IO.println(user.userId() + " " + row.group().product().orElse(null) + ": " + row.cost().amount()) ); } } ``` ```php PHP use Anthropic\Beta\Organization\Analytics\AnalyticsReportUserActor; // ... $client = new Client(); $rows = $client->beta->organization->analytics->cost->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), actorTypes: ['user_actor'], groupBy: ['actor', 'product'], limit: 100, ); foreach ($rows->pagingEachItem() as $row) { $actor = $row->group->actor; if ($actor instanceof AnalyticsReportUserActor) { echo "{$actor->userID} {$row->group->product}: {$row->cost->amount}\n"; } } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.cost.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 10, 1), actor_types: [:user_actor], group_by: [:actor, :product], limit: 100 ) page.auto_paging_each do |row| actor = row.group.actor if actor.is_a?(Anthropic::Models::Beta::Organization::BetaAnalyticsReportUserActor) puts "#{actor.user_id} #{row.group.product}: #{row.cost.amount}" end end ``` ## 자주 묻는 질문 ### 기본 워크스페이스는 어떻게 표시되나요? Claude Console 조직의 기본 워크스페이스는 다른 모든 워크스페이스와 마찬가지로 자체 `wrkspc_` ID를 가집니다. 기본 워크스페이스에 대한 행의 `workspace_id`에는 해당 ID가 들어 있으며, `workspace_ids[]`로 이를 필터링할 수 있습니다. [List Workspaces](https://platform.claude.com/docs/ko/api/organization/workspaces/list)는 `include_default=true`를 전달하지 않는 한 기본 워크스페이스를 제외합니다. 익숙하지 않은 `workspace_id`가 기본 워크스페이스인지 확인하려면 [Get Workspace](https://platform.claude.com/docs/ko/api/organization/workspaces/retrieve)에 전달하세요. 기본 워크스페이스는 `"name": "Default"`를 반환합니다. ### Claude Code의 사용자별 비용은 어떻게 얻나요? `products[]=claude_code&group_by[]=actor`로 비용 엔드포인트를 호출하세요. Claude Console 조직은 사용자별 Claude Code 활동과 예상 비용을 보고하는 [Claude Code Analytics API](https://platform.claude.com/docs/ko/manage-claude/claude-code-analytics-api)도 사용할 수 있습니다. ## 참고 항목 * [Usage and Cost API](https://platform.claude.com/docs/ko/manage-claude/usage-cost-api)(레거시) * [Analytics API](https://platform.claude.com/docs/ko/manage-claude/analytics-api): 조직에 필요한 분석 API 및 키 유형 * [Claude Code Analytics API](https://platform.claude.com/docs/ko/manage-claude/claude-code-analytics-api) * [Admin API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization) * [가격](https://platform.claude.com/docs/ko/about-claude/pricing)