用量與成本 API

Admin API 不適用於個人帳戶。 若要與團隊成員協作並新增成員，請在 Console → Settings → Organization 中設定您的組織。

Usage & Cost Admin API 提供程式化且細緻的方式，讓您存取組織的歷史 API 用量與成本資料。這些資料與 Claude Console 中 Usage 和 Cost 頁面所提供的資訊類似。

此 API 讓您能夠更有效地監控、分析及最佳化您的 Claude 實作：

精確的用量追蹤： 取得精確的 token 計數與使用模式，而非僅依賴回應中的 token 計數
成本對帳： 將內部記錄與 Anthropic 帳單進行比對，供財務與會計團隊使用
產品效能與改進： 監控產品效能，同時衡量系統變更是否帶來改善，或設定警示
速率限制與 Priority Tier 最佳化： 最佳化提示快取等功能或特定提示，以充分利用已分配的容量，或購買專用容量。
進階分析： 執行比 Console 所提供更深入的資料分析

需要 Admin API 金鑰

此 API 是 Admin API 的一部分。這些端點需要 Admin API 金鑰（以 sk-ant-admin... 開頭），與標準 API 金鑰不同。只有具備管理員角色的組織成員才能透過 Claude Console 配置 Admin API 金鑰。

AWS 上的 Claude Platform： 目前尚未提供程式化的用量與成本 API 端點。請改為在 Claude Console 的 Usage 和 Cost 頁面中檢視用量與成本資料。

合作夥伴解決方案

領先的可觀測性平台提供現成可用的整合方案，讓您無需撰寫自訂程式碼即可監控 Claude API 的用量與成本。這些整合提供儀表板、警示與分析功能，協助您有效管理 API 用量。

CloudZero

用於追蹤與預測成本的雲端智慧平台

快速入門

取得您組織過去 7 天的每日用量：

cURL

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-15T00:00:00Z&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

為整合設定 User-Agent 標頭

如果您正在建置整合，請設定 User-Agent 標頭以協助我們了解使用模式：

User-Agent: YourApp/1.0.0 (https://yourapp.com)

用量 API

透過 /v1/organizations/usage_report/messages 端點，追蹤整個組織的 token 消耗量，並依模型、工作區與服務層級進行詳細分類。

主要概念

時間區間（Time buckets）：以固定間隔（1m、1h 或 1d）彙總用量資料
Token 追蹤：測量未快取輸入、已快取輸入、快取建立與輸出 token
篩選與分組：依 API 金鑰、工作區、模型、服務層級、上下文視窗、資料駐留或速度（測試版）進行篩選，並依這些維度對結果進行分組
伺服器工具使用：追蹤伺服器端工具（如網頁搜尋）的使用情況

如需完整的參數詳細資訊與回應結構描述，請參閱用量 API 參考文件。

基本範例

依模型分類的每日用量

cURL

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

含篩選條件的每小時用量

cURL

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-15T00:00:00Z&\
ending_at=2025-01-15T23:59:59Z&\
models[]=claude-opus-4-8&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

依 API 金鑰與工作區篩選用量

cURL

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\
api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

若要擷取您組織的 API 金鑰 ID，請使用 List API Keys 端點。

若要擷取您組織的工作區 ID，請使用 List Workspaces 端點，或在 Claude Console 中查找您組織的工作區 ID。

資料駐留

透過使用 inference_geo 維度對用量進行分組與篩選，追蹤您的資料駐留控制。這對於驗證整個組織的地理路由非常有用。

cURL

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

您也可以篩選特定地理位置。有效值為 global、us 和 not_available：

cURL

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

2026 年 2 月之前發布的模型（Claude Opus 4.6 和 Claude Sonnet 4.6 之前的版本）不支援 inference_geo 請求參數，因此其用量報告在此維度會回傳 "not_available"。您可以在 inference_geos[] 中使用 not_available 作為篩選值來鎖定這些模型。

快速模式（研究預覽）

透過使用 speed 維度進行分組與篩選，追蹤快速模式的用量。這對於監控標準模式與快速模式的用量非常有用。

cURL

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

您也可以篩選特定速度。有效值為 standard 和 fast：

cURL

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
speeds[]=fast&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

speeds[] 篩選器與 speed group_by 值都需要 fast-mode-2026-02-01 測試版標頭。

時間粒度限制

粒度	預設限制	最大限制	使用情境
`1m`	60 個區間	1440 個區間	即時監控
`1h`	24 個區間	168 個區間	每日模式
`1d`	7 個區間	31 個區間	每週／每月報告

成本 API

透過 /v1/organizations/cost_report 端點擷取以美元計價的服務層級成本明細。

主要概念

貨幣：所有成本均以美元計價，以最小單位（美分）的十進位字串形式回報
成本類型：追蹤 token 用量、網頁搜尋與程式碼執行成本
分組：依工作區或描述對成本進行分組，以取得詳細明細。依 description 分組時，回應會包含已解析的欄位，例如 model 和 inference_geo
時間區間：僅支援每日粒度（1d）

如需完整的參數詳細資訊與回應結構描述，請參閱成本 API 參考文件。

Priority Tier 成本採用不同的計費模式，不包含在成本端點中。請改為透過用量端點追蹤 Priority Tier 用量。

基本範例

cURL

curl "https://api.anthropic.com/v1/organizations/cost_report?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
group_by[]=workspace_id&\
group_by[]=description" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

分頁

兩個端點都支援大型資料集的分頁功能：

發出初始請求
如果 has_more 為 true，請在下一個請求中使用 next_page 值
持續進行直到 has_more 為 false

cURL

# 第一個請求
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

# 回應包含："has_more": true, "next_page": "page_xyz..."

# 使用分頁的下一個請求
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7&\
page=page_xyz..." \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

常見使用情境

在 Claude Cookbook 中探索詳細的實作方式：

每日用量報告：追蹤 token 消耗趨勢
成本歸屬：依工作區分配費用以進行內部計費
快取效率：測量並最佳化提示快取
預算監控：為支出門檻設定警示
CSV 匯出：為財務團隊產生報告

常見問題

資料的即時性如何？

用量與成本資料通常會在 API 請求完成後 5 分鐘內出現，但偶爾可能會有較長的延遲。

建議的輪詢頻率為何？

此 API 支援持續使用時每分鐘輪詢一次。對於短時間的突發需求（例如下載分頁資料），可接受更頻繁的輪詢。對於需要頻繁更新的儀表板，請快取結果。

如何追蹤程式碼執行用量？

程式碼執行成本會出現在成本端點中，在 description 欄位下歸類為 Code Execution Usage。程式碼執行不包含在用量端點中。

如何追蹤 Priority Tier 用量？

在用量端點中依 service_tier 進行篩選或分組，並尋找 priority 值。Priority Tier 成本不會出現在成本端點中。

Workbench 用量會如何處理？

來自 Workbench 的 API 用量不會與任何 API 金鑰關聯，因此即使依該維度分組，api_key_id 也會是 null。

預設工作區如何表示？

歸屬於預設工作區的用量與成本，其 workspace_id 值為 null。

如何取得 Claude Code 的每位使用者成本明細？

請使用 Claude Code Analytics API，它提供每位使用者的預估成本與生產力指標，且不會有依大量 API 金鑰分類成本時的效能限制。對於使用大量金鑰的一般 API 用量，請使用用量 API 追蹤 token 消耗量作為成本的替代指標。

另請參閱

用量與成本 API 可協助您為使用者提供更好的體驗、管理成本並維持您的速率限制。深入了解以下其他功能：

Admin API
Admin API 參考文件
定價
提示快取 - 透過快取最佳化成本
批次處理 - 批次請求享 50% 折扣
速率限制 - 了解用量層級
速率限制 API - 讀取您已設定的速率限制
資料駐留 - 控制推論地理位置