--- title: 用量與成本分析 API url: https://platform.claude.com/docs/zh-TW/manage-claude/usage-cost-analytics-api description: 依模型、工作區、API 金鑰、執行者等維度，查詢您的 Claude Console 或 Claude Enterprise 組織的 token 用量與成本。 --- **Admin API 不適用於個人帳戶。** 若要與團隊成員協作並新增成員，請在 Claude Console 的 [Organization](https://platform.claude.com/settings/organization) 頁面（`platform.claude.com/settings/organization`）設定您的組織。 用量與成本分析 API 會回報您組織的歷史 token 用量與成本，並依您選擇的維度進行細分，例如模型、工作區、API 金鑰，或每個請求背後的使用者或服務帳戶。對於 Claude Console 組織，這些資料與 Claude Console 的 [Usage](https://platform.claude.com/usage) 和 [Cost](https://platform.claude.com/cost) 頁面所顯示的內容類似。 此 API 有兩個端點： * `GET /v1/organizations/analytics/usage` 回報 token 數量與請求數量。 * `GET /v1/organizations/analytics/cost` 回報以美元計的成本。 用量與成本分析 API 目前為 beta 版。請在每個請求中傳送 `anthropic-beta: analytics-usage-cost-2026-08-24` 標頭和 [`anthropic-version`](https://platform.claude.com/docs/zh-TW/api/versioning) 標頭。SDK 和 `ant` CLI 會為您傳送這兩個標頭，並在您讀取結果時擷取其餘頁面，因此 `limit` 只會設定頁面大小。 使用此 API 來： * **歸屬支出：** 依工作區、API 金鑰、模型、服務層級或發出每個請求的身分，細分成本與 token 用量。 * **找出最大用量者：** 依 token、請求或成本對結果排名，以回答諸如「本月哪些 API 金鑰花費最多？」之類的問題。 * **建立時間序列：** 將結果分割為每日、每小時或每分鐘的區間，用於儀表板和財務報告。 * **一次整合：** 相同的端點、參數和回應欄位同時適用於 Claude Console 和 Claude Enterprise 組織。 **需要 Admin API 金鑰** Claude Console 組織使用 [Admin API 金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api-keys#create-a-key-for-a-claude-console-organization)或其他 [Admin API 憑證](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api#authentication)。Claude Enterprise 組織使用具有 `read:analytics` 範圍的金鑰，該金鑰由主要擁有者在組織啟用 Analytics API 後於 claude.ai 中建立；請參閱[取得 Claude Enterprise Analytics API 的存取權](https://platform.claude.com/docs/zh-TW/manage-claude/analytics-api#get-access-to-the-claude-enterprise-analytics-api)。無論哪種情況，請將 `ANTHROPIC_API_KEY` 環境變數設定為該金鑰；本頁的範例會從中讀取金鑰。 如果您使用 Admin API 金鑰呼叫這些端點，請為收集這些資料的服務提供專屬的金鑰，將其儲存在機密管理工具中，並定期輪替；在建立金鑰時設定[金鑰到期時間](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-expiration)即可強制執行輪替。在可行的情況下，請改用具有 [`org:admin` 範圍](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#oauth-scopes)的 [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation) 規則，讓服務取得短期權杖，如此便沒有可能外洩的長期金鑰。 **Claude Platform on AWS：** 兩個端點皆可使用。請求使用 Claude Platform on AWS 的基礎 URL 和驗證方式，而非 Admin API 金鑰（請參閱[發出請求](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws#making-requests)），並由 AWS IAM 透過 [`ListAccountUsage` 和 `ListAccountCost` 動作](https://platform.claude.com/docs/zh-TW/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)：** 兩個端點皆可使用。請透過[組織層級的基礎 URL](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#making-requests)，使用 Google Cloud 憑證（而非 Admin API 金鑰）呼叫這些端點。`/usage` 端點需要 `usageAnalytics.list` [IAM 權限](https://platform.claude.com/docs/zh-TW/api/claude-models-on-google-cloud-anthropic-managed-iam-permissions)，而 `/cost` 端點需要 `costAnalytics.list`。 ## 快速入門 取得九月第一週的每日 token 用量，每個模型每天一列： ```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 標頭** 如果您正在建置整合，請設定您的 User-Agent 標頭，以協助 Anthropic 了解使用模式： ```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[]` 最多可接受五個維度。 * **每個組合一列：** 每一列代表已分組維度的一個組合，且每個有用量或成本的組合在查詢的所有頁面中恰好出現一次。若未指定 `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` 會讓最舊的在前），且在每個區間內最大的列排在前面。請以零填補空的區間。 * **篩選器可與分組並用：** 大多數可分組的維度都有對應的清單篩選器，使用方括號表示法，例如 `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/zh-TW/api/beta/organization/analytics/usage/list) 和 [成本](https://platform.claude.com/docs/zh-TW/api/beta/organization/analytics/cost/list) 的 API 參考文件列出了所有維度、篩選器和值。 ### 執行者 `actor` 維度表示請求歸屬的對象：使用者、服務帳戶、聯合雲端身分（AWS 或 Google Cloud 主體，適用於透過其雲端平台存取 Claude 的組織），或者在請求背後沒有上述任何身分時，即為 API 金鑰本身。當您依 `actor` 分組時，每一列的 `actor` 是一個物件，其 `type` 說明它屬於哪一種。無法歸屬於任何身分的用量，其 `actor` 為 `null`。 [個人金鑰和服務帳戶金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-types)會以其所連結的使用者或服務帳戶身分運作，因此其請求會將該身分顯示為 `actor`，並將金鑰顯示在 `api_key_id` 中。舊版工作區金鑰未連結到任何身分，因此金鑰會同時顯示為 `actor` 和 `api_key_id`。例外是成員以其 Claude Console 帳戶登入時 Claude Code 所建立的金鑰：它位於 [Claude Code 工作區](https://platform.claude.com/docs/zh-TW/manage-claude/workspaces#claude-code-workspace)中，其用量會歸屬於該成員。未使用 API 金鑰發出的請求（例如從 Claude Console 發出，或使用 [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation) 權杖發出）的 `api_key_id` 為 `null`；聯合工作負載的 `actor` 是其服務帳戶。若要在 `api_key_ids[]` 篩選器中包含沒有 API 金鑰的用量，請加入一個空項目：`api_key_ids[]=`。 `api_key_ids[]` 和 `actor_ids[]` 篩選器回答的是不同的問題。`api_key_ids[]=apikey_...` 會比對該金鑰驗證過的所有請求，無論其歸屬於誰。`actor_ids[]=apikey_...` 則只比對歸屬於該金鑰本身的請求。 ## 用量端點 `GET /v1/organizations/analytics/usage` 依類型傳回 token 數量。`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/zh-TW/api/organization/api_keys/list) 和 [List Workspaces](https://platform.claude.com/docs/zh-TW/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 美元。`order_by` 接受 `amount`（預設值）、`list_amount` 或 `time`。 有兩個額外的維度僅存在於此端點，且不計入五個維度的上限：`group_by[]=cost_type` 會將每一列分割為每種成本類型各一列，而 `group_by[]=token_type` 會將 token 成本分割為每種 token 類型各一列。`limit` 也不適用於這兩個維度，因此一個頁面可能包含超過 `limit` 的列數。例如，一個月內依模型、成本類型和 token 類型的成本： ```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 ``` 對於每個模型，回應包含五個 `tokens` 列（每種 token 類型各一列），再加上 `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` 貢獻的 token 成本為零，因為您的承諾已涵蓋這些請求；承諾費用會另行計費，不包含在這些資料中。這些請求上的網頁搜尋以標準費率計費。超出您承諾容量的請求會以標準層級處理並計價。 ## 日期範圍與時間區間 * 時間戳記採用帶有 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` 在各頁之間完全相同。 ## 從用量與成本 API 遷移 本節適用於呼叫舊版[用量與成本 API](https://platform.claude.com/docs/zh-TW/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`）、方括號表示法、分頁欄位名稱，以及 token 和成本欄位名稱都會沿用。變更之處如下： | 用量與成本 API | 用量與成本分析 API | | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 無 beta 標頭 | 每個請求都需要 `anthropic-beta: analytics-usage-cost-2026-08-24` | | 資料通常在 5 分鐘內出現 | 資料通常在 4 小時內更新，最長可能需要 24 小時（請參閱[資料新鮮度](https://platform.claude.com/docs/zh-TW/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/zh-TW/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/zh-TW/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/zh-TW/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"`，另加上 `list_amount`。 | | 用量報告中不含程式碼執行；沒有請求數量 | 程式碼執行會以 `model: null` 的用量列出現；兩個端點都新增 `requests`，用量列則新增 `total_tokens` | 若要重現舊版的每日報告，請以相同的 `group_by[]` 請求 `time_bucket_width=1d`，使用 `limit=1000` 逐頁讀取，然後依 `starting_at` 將列分組，並以零填補缺少的日期。加入 `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 ``` 依工作區、模型、服務層級、上下文視窗和推論地理位置的每日成本，並依成本類型和 token 類型分割： ```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 用量與成本報告遷移 本節適用於呼叫 [Claude Enterprise Analytics API](https://platform.claude.com/docs/zh-TW/manage-claude/analytics-api) 中 `/v1/organizations/analytics/` 下報告端點 `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/zh-TW/manage-claude/analytics-api#working-with-the-api)都會沿用。唯一新增的標頭是 `analytics-usage-cost-2026-08-24` beta 標頭。變更之處如下： | Claude Enterprise 報告 | 用量與成本分析 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`。若不使用此篩選器，您還會取得非使用者身分的列，以及未歸屬用量的 `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` 之使用者的列；其他身分的列和 `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[]` 依其篩選。除非您傳入 `include_default=true`，否則 [List Workspaces](https://platform.claude.com/docs/zh-TW/api/organization/workspaces/list) 不會列出預設工作區。若要確認不熟悉的 `workspace_id` 是否為預設工作區，請將其傳給 [Get Workspace](https://platform.claude.com/docs/zh-TW/api/organization/workspaces/retrieve)：預設工作區會傳回 `"name": "Default"`。 ### 如何取得 Claude Code 每位使用者的成本？ 使用 `products[]=claude_code&group_by[]=actor` 呼叫成本端點。Claude Console 組織也可以使用 [Claude Code Analytics API](https://platform.claude.com/docs/zh-TW/manage-claude/claude-code-analytics-api)，它會回報每位使用者的 Claude Code 活動和預估成本。 ## 另請參閱 * [用量與成本 API](https://platform.claude.com/docs/zh-TW/manage-claude/usage-cost-api)（舊版） * [分析 API](https://platform.claude.com/docs/zh-TW/manage-claude/analytics-api)：您的組織需要哪種分析 API 和金鑰類型 * [Claude Code Analytics API](https://platform.claude.com/docs/zh-TW/manage-claude/claude-code-analytics-api) * [Admin API 參考文件](https://platform.claude.com/docs/zh-TW/api/beta/organization) * [定價](https://platform.claude.com/docs/zh-TW/about-claude/pricing)