用量與成本分析 API

用量與成本分析 API 會回報您組織的歷史 token 用量與成本，並依您選擇的維度進行細分，例如模型、工作區、API 金鑰，或每個請求背後的使用者或服務帳戶。對於 Claude Console 組織，這些資料與 Claude Console 的 Usage 和 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 標頭。SDK 和 ant CLI 會為您傳送這兩個標頭，並在您讀取結果時擷取其餘頁面，因此 limit 只會設定頁面大小。

使用此 API 來：

• 歸屬支出： 依工作區、API 金鑰、模型、服務層級或發出每個請求的身分，細分成本與 token 用量。
• 找出最大用量者： 依 token、請求或成本對結果排名，以回答諸如「本月哪些 API 金鑰花費最多？」之類的問題。
• 建立時間序列： 將結果分割為每日、每小時或每分鐘的區間，用於儀表板和財務報告。
• 一次整合： 相同的端點、參數和回應欄位同時適用於 Claude Console 和 Claude Enterprise 組織。

快速入門

取得九月第一週的每日 token 用量，每個模型每天一列：

client = anthropic.Anthropic()

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

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

回應中每個有用量的模型每天各有一列，依 total_tokens 由大到小排列。此範例顯示單一列：

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

結果的結構

• 每一列都有三個部分： starting_at 和 ending_at 表示該列涵蓋的期間，group 包含所有維度，而 usage（在成本端點上則為 cost）包含指標。
• 未分組的維度為 null： group 中的維度除非列在 group_by[] 中，否則為 null。已分組的維度在沒有對應值的列上也會是 null，例如程式碼執行用量上的 model。group_by[] 最多可接受五個維度。
• 每個組合一列： 每一列代表已分組維度的一個組合，且每個有用量或成本的組合在查詢的所有頁面中恰好出現一次。若未指定 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，當您的組織無法使用團隊功能時，它會改為傳回錯誤。用量 和 成本 的 API 參考文件列出了所有維度、篩選器和值。

執行者

actor 維度表示請求歸屬的對象：使用者、服務帳戶、聯合雲端身分（AWS 或 Google Cloud 主體，適用於透過其雲端平台存取 Claude 的組織），或者在請求背後沒有上述任何身分時，即為 API 金鑰本身。當您依 actor 分組時，每一列的 actor 是一個物件，其 type 說明它屬於哪一種。無法歸屬於任何身分的用量，其 actor 為 null。

個人金鑰和服務帳戶金鑰會以其所連結的使用者或服務帳戶身分運作，因此其請求會將該身分顯示為 actor，並將金鑰顯示在 api_key_id 中。舊版工作區金鑰未連結到任何身分，因此金鑰會同時顯示為 actor 和 api_key_id。例外是成員以其 Claude Console 帳戶登入時 Claude Code 所建立的金鑰：它位於 Claude Code 工作區中，其用量會歸屬於該成員。未使用 API 金鑰發出的請求（例如從 Claude Console 發出，或使用 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 金鑰一週的用量，並依服務層級細分（每個層級一列，涵蓋整週）：

client = anthropic.Anthropic()

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

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

若要查詢 API 金鑰和工作區 ID，請使用 List API Keys 和 List Workspaces 端點或 Claude Console。

若要找出一個月內發出最多請求的使用者、服務帳戶和 API 金鑰：

client = anthropic.Anthropic()

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

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

成本端點

GET /v1/organizations/analytics/cost 接受與 /usage 端點相同的篩選條件、維度和時間區間。每一列的 cost 物件包含 amount（套用折扣後、套用任何抵用額度前的成本）、list_amount（以定價計算的成本）、currency（一律為 "USD"）和 requests。金額是以美分為單位、帶有六位小數的十進位字串："41280.000000" 即為 412.80 美元。order_by 接受 amount（預設值）、list_amount 或 time。

有兩個額外的維度僅存在於此端點，且不計入五個維度的上限：group_by[]=cost_type 會將每一列分割為每種成本類型各一列，而 group_by[]=token_type 會將 token 成本分割為每種 token 類型各一列。limit 也不適用於這兩個維度，因此一個頁面可能包含超過 limit 的列數。例如，一個月內依模型、成本類型和 token 類型的成本：

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}"
    )

對於每個模型，回應包含五個 tokens 列（每種 token 類型各一列），再加上 web_search、code_execution 和 session_usage 各一列。其中一列如下：

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

group 物件包含所有維度，此處已省略部分內容。指定 group_by[]=cost_type 或 token_type 時，每一列的 requests 皆為 null。

日期範圍與時間區間

• 時間戳記採用帶有 UTC 偏移的 RFC 3339 格式，例如 2026-09-01T00:00:00Z。starting_at 包含在內，ending_at 則不包含在內。
• starting_at 必須在 2026 年 1 月 1 日當天或之後，且在過去 365 天內。單一請求最多可涵蓋 31 天；ending_at 預設為 starting_at 之後 31 天或目前時間，以較早者為準。
• 只要設定了 time_bucket_width，就必須提供 ending_at；使用 time_bucket_width=1m 時，單一請求最多可涵蓋 24 小時。
• 範圍的兩端都會向下捨入至 UTC 區間邊界；若未設定 time_bucket_width，則向下捨入至整點。例如，使用 time_bucket_width=1h 時，2026-09-01T10:43:00Z 的 starting_at 會被視為 2026-09-01T10:00:00Z，而 2026-09-01T15:43:00Z 的 ending_at 會被視為 2026-09-01T15:00:00Z，因此回應涵蓋 UTC 10:00 至 15:00。

資料新鮮度

每個回應都包含 data_refreshed_at 時間戳記，該時間之後的用量會缺漏或不完整。當請求範圍的任何部分都尚無可用資料時，data_refreshed_at 為 null，且 data 為空。資料通常會在實際用量發生後 4 小時內更新，最長可能需要 24 小時。隨著延遲事件到達和對帳作業執行，數值可能會被修訂，直到該日曆月結束後約 7 天為止。例如，10 月 1 日的數值可能會變動到約 11 月 7 日。若要在重複呼叫中取得穩定的結果，請將 ending_at 設定在您已看過的 data_refreshed_at 當時或之前；若要取得最終總計，請只查詢至少已結束 7 天的月份。分頁查詢的每一頁都讀取相同的資料快照，因此 data_refreshed_at 在各頁之間完全相同。

從用量與成本 API 遷移

本節適用於呼叫舊版用量與成本 API（/v1/organizations/usage_report/messages 和 /v1/organizations/cost_report）的 Claude Console 組織。您的 Admin API 金鑰、anthropic-version 標頭、starting_at 和 ending_at、區間寬度值（1m、1h、1d）、方括號表示法、分頁欄位名稱，以及 token 和成本欄位名稱都會沿用。變更之處如下：

若要重現舊版的每日報告，請以相同的 group_by[] 請求 time_bucket_width=1d，使用 limit=1000 逐頁讀取，然後依 starting_at 將列分組，並以零填補缺少的日期。加入 order_by=time&order=asc 即可依序取得各日。依模型細分的 1 週每日用量，遷移前：

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

遷移後：

client = anthropic.Anthropic()

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

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

依工作區、模型、服務層級、上下文視窗和推論地理位置的每日成本，並依成本類型和 token 類型分割：

client = anthropic.Anthropic()

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

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

從 Claude Enterprise 用量與成本報告遷移

本節適用於呼叫 Claude Enterprise 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、游標規則，以及組織層級的速率限制都會沿用。唯一新增的標頭是 analytics-usage-cost-2026-08-24 beta 標頭。變更之處如下：

一個月內每位使用者的成本，遷移前：

client = anthropic.Anthropic()

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

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

遷移後，並新增依產品的細分：

client = anthropic.Anthropic()

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

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

常見問題

預設工作區如何表示？

Claude Console 組織的預設工作區與其他所有工作區一樣，都有自己的 wrkspc_ ID。預設工作區的列會在 workspace_id 中包含該 ID，您也可以使用 workspace_ids[] 依其篩選。除非您傳入 include_default=true，否則 List Workspaces 不會列出預設工作區。若要確認不熟悉的 workspace_id 是否為預設工作區，請將其傳給 Get Workspace：預設工作區會傳回 "name": "Default"。

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

使用 products[]=claude_code&group_by[]=actor 呼叫成本端點。Claude Console 組織也可以使用 Claude Code Analytics API，它會回報每位使用者的 Claude Code 活動和預估成本。

另請參閱

• 用量與成本 API（舊版）
• 分析 API：您的組織需要哪種分析 API 和金鑰類型
• Claude Code Analytics API
• Admin API 參考文件
• 定價