用量與成本 API

透過 Usage & Cost Admin API，以程式化方式存取您組織的 API 用量與成本資料。

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

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

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

Claude Enterprise 組織則改用 Analytics API 金鑰搭配另一個 API；請參閱您需要哪一個 API？。

您需要哪一個 API？

Anthropic 透過兩個 API 提供成本與用量報告，取決於您的組織所管理的 Claude 產品：

您的組織	API	金鑰類型
Claude Console（Claude Platform）	本頁所述的 Usage and Cost Admin API	Admin API 金鑰（`sk-ant-admin01-...`）或其他 Admin API 憑證
Claude Enterprise（claude.ai）	Claude Enterprise Analytics API 的成本與用量端點	Analytics API 金鑰

Claude Enterprise 的上層組織不會出現在 Claude Console 中，也沒有 Admin API 金鑰，因此對它們而言，Analytics API 金鑰是取得這些資料的唯一途徑。請參閱 Analytics API，了解如何建立各種金鑰類型，以及 Claude Enterprise 成本資料適用於哪些方案。

合作夥伴解決方案

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

CloudZero

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

Datadog

具備自動追蹤與監控功能的 LLM 可觀測性

Grafana Cloud

無代理程式整合，提供開箱即用的儀表板與警示，輕鬆實現 LLM 可觀測性

Harness

用於雲端與 AI 成本管理的 FinOps 平台

Honeycomb

透過 OpenTelemetry 進行進階查詢與視覺化

Vantage

用於 LLM 成本與用量可觀測性的 FinOps 平台

快速開始

取得您組織過去 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

用量 API

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

關鍵概念

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

如需完整的參數詳細資訊與回應結構描述，請參閱用量 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "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-5&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

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

cURL

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

資料駐留

透過 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

快速模式（研究預覽）

透過 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

時間粒度限制

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

成本 API

使用 /v1/organizations/cost_report 端點，取得以美元計價的服務層級成本明細。

關鍵概念

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

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

基本範例

cURL

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

分頁

兩個端點皆支援大型資料集的分頁：

發出您的初始請求。
若 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

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

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

常見使用情境

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

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

常見問題

資料的即時性如何？

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

建議的輪詢頻率為何？

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

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

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

如何追蹤 Priority Tier 用量？

在用量端點中依 service_tier 進行篩選或分組，並尋找 priority 值。Priority Tier 成本無法在成本端點中取得。

playground 的用量會如何處理？

來自 Claude Console 中 playground（以及其前身舊版 Workbench）的 API 用量不會與 API 金鑰關聯，因此即使依該維度分組，api_key_id 仍會是 null。

預設工作區如何表示？

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

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

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

另請參閱

使用用量與成本 API 為您的使用者提供更好的體驗、管理成本，並維護您的速率限制。進一步了解以下其他功能：

Admin API
Admin API 參考文件
Analytics API - 您的組織需要哪一個分析 API 與金鑰類型
定價
提示快取 - 透過快取最佳化成本
批次處理 - 批次請求享 50% 折扣
速率限制 - 了解用量層級
Rate Limits API - 讀取您已設定的速率限制
資料駐留 - 控制推論地理位置

您需要哪一個 API？

合作夥伴解決方案

快速開始

用量 API

關鍵概念

基本範例

依模型的每日用量

含篩選條件的每小時用量

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

資料駐留

快速模式（研究預覽）

時間粒度限制

成本 API

關鍵概念

基本範例

分頁

常見使用情境

常見問題

資料的即時性如何？

建議的輪詢頻率為何？

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

如何追蹤 Priority Tier 用量？

playground 的用量會如何處理？

預設工作區如何表示？

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

另請參閱

您需要哪一個 API？

合作夥伴解決方案

快速開始

用量 API

關鍵概念

基本範例

依模型的每日用量

含篩選條件的每小時用量

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

資料駐留

快速模式（研究預覽）

時間粒度限制

成本 API

關鍵概念

基本範例

分頁

常見使用情境

常見問題

資料的即時性如何？

建議的輪詢頻率為何？

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

如何追蹤 Priority Tier 用量？

playground 的用量會如何處理？

預設工作區如何表示？

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

另請參閱