---
title: 用量與成本 API
url: https://platform.claude.com/docs/zh-TW/manage-claude/usage-cost-api
description: 透過用量與成本 Admin API，以程式化方式存取您組織的 API 用量與成本資料。
---

<Tip>
  **Admin API 不適用於個人帳戶。** 若要與團隊成員協作並新增成員，請在 Claude Console 的 [Organization](https://platform.claude.com/settings/organization) 頁面（`platform.claude.com/settings/organization`）設定您的組織。
</Tip>

用量與成本 Admin API 提供以程式化且細緻的方式存取您組織的歷史 API 用量與成本資料。這些資料與 Claude Console 中 [Usage](https://platform.claude.com/usage) 頁面（`platform.claude.com/usage`）和 [Cost](https://platform.claude.com/cost) 頁面（`platform.claude.com/cost`）上提供的資訊類似。

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

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

<Check>
  **需要 Admin API 憑證。** 這些端點屬於 Admin API 的一部分。您可以使用 [Admin API 金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api-keys)、具有 `org:admin` 範圍的 OAuth 權杖，或未限定於特定工作區的個人或服務帳戶金鑰來存取它們；工作區 API 金鑰無法使用。詳情請參閱[驗證](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api#authentication)。
</Check>

Claude Enterprise 組織則改用 Analytics API 金鑰搭配另一個 API；請參閱[您需要哪一個 API？](https://platform.claude.com/docs/zh-TW/manage-claude/usage-cost-api#which-api-do-you-need)。

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

## 您需要哪一個 API？

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

| 您的組織                            | API                                                                                                                | 金鑰類型                                                                                                                                |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Claude Console（Claude Platform） | 本頁所述的 Usage and Cost Admin API                                                                                     | Admin API 金鑰（`sk-ant-admin01-...`）或其他 [Admin API 憑證](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api#authentication) |
| Claude Enterprise（claude.ai）    | [Claude Enterprise Analytics API](https://platform.claude.com/docs/zh-TW/api/beta/organization/analytics) 的成本與用量端點 | Analytics API 金鑰                                                                                                                    |

Claude Enterprise 的上層組織不會出現在 Claude Console 中，也沒有 Admin API 金鑰，因此對它們而言，Analytics API 金鑰是取得這些資料的唯一途徑。請參閱 [Analytics API](https://platform.claude.com/docs/zh-TW/manage-claude/analytics-api)，了解如何建立各種金鑰類型，以及 Claude Enterprise 成本資料適用於哪些方案。

## 合作夥伴解決方案

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

<CardGroup cols={3}>
  <Card title="CloudZero" icon="chart" href="https://docs.cloudzero.com/docs/connections-anthropic">
    用於追蹤和預測成本的雲端智慧平台
  </Card>

  <Card title="Datadog" icon="chart" href="https://docs.datadoghq.com/integrations/anthropic/">
    具備自動追蹤與監控的 LLM 可觀測性
  </Card>

  <Card title="Grafana Cloud" icon="chart" href="https://grafana.com/docs/grafana-cloud/monitor-infrastructure/integrations/integration-reference/integration-anthropic/">
    無代理程式整合，提供開箱即用的儀表板和警示，輕鬆實現 LLM 可觀測性
  </Card>

  <Card title="Harness" icon="chart" href="https://developer.harness.io/docs/cloud-cost-management/provider-integrations/ai-providers/anthropic/">
    用於雲端與 AI 成本管理的 FinOps 平台
  </Card>

  <Card title="Honeycomb" icon="polygon" href="https://docs.honeycomb.io/integrations/anthropic-usage-monitoring/">
    透過 OpenTelemetry 進行進階查詢與視覺化
  </Card>

  <Card title="Tempo" icon="chart" href="https://help.tempo.io/workforceintelligence/latest/connect-to-anthropic">
    將用量與成本歸屬至 Jira 工作項目
  </Card>

  <Card title="Vantage" icon="chart" href="https://docs.vantage.sh/connecting_anthropic">
    用於 LLM 成本與用量可觀測性的 FinOps 平台
  </Card>
</CardGroup>

## 快速開始

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

```bash 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"
```

<Tip>
  **為整合設定 User-Agent 標頭**

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

  ```text wrap
  User-Agent: YourApp/1.0.0 (https://yourapp.com)
  ```
</Tip>

## 用量 API

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

### 關鍵概念

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

如需完整的參數詳細資訊與回應結構描述，請參閱[用量 API 參考文件](https://platform.claude.com/docs/zh-TW/api/beta/organization/usage_report/retrieve_messages)。

### 基本範例

#### 依模型的每日用量

```bash 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"
```

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

```bash 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-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 金鑰與工作區篩選用量

```bash 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"
```

<Tip>
  若要取得您組織的 API 金鑰 ID，請使用 [List API Keys](https://platform.claude.com/docs/zh-TW/api/organization/api_keys/list) 端點。

  若要取得您組織的工作區 ID，請使用 [List Workspaces](https://platform.claude.com/docs/zh-TW/api/organization/workspaces/list) 端點，或在 Claude Console 中查看您組織的工作區 ID。
</Tip>

#### 資料駐留

透過 `inference_geo` 維度對用量進行分組與篩選，以追蹤您的[資料駐留控制](https://platform.claude.com/docs/zh-TW/manage-claude/data-residency)。這對於驗證整個組織的地理路由非常有用。

```bash 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`：

```bash 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"
```

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

#### 快速模式

透過 `speed` 維度進行分組與篩選，以追蹤[快速模式](https://platform.claude.com/docs/zh-TW/build-with-claude/fast-mode)的用量。這對於監控標準模式與快速模式的用量非常有用。

```bash 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 "x-api-key: $ANTHROPIC_ADMIN_KEY"
```

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

```bash 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 "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 參考文件](https://platform.claude.com/docs/zh-TW/api/beta/organization/cost_report/retrieve)。

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

### 基本範例

```bash 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"
```

## 分頁

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

1. 發出您的初始請求。
2. 若 `has_more` 為 `true`，請在下一個請求中使用 `next_page` 值。
3. 持續進行，直到 `has_more` 為 `false`。

```bash 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](https://platform.claude.com/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](https://platform.claude.com/docs/zh-TW/manage-claude/claude-code-analytics-api)，它提供每位使用者的預估成本與生產力指標，且不會有依大量 API 金鑰拆分成本所帶來的效能限制。對於使用大量金鑰的一般 API 用量，請使用[用量 API](https://platform.claude.com/docs/zh-TW/manage-claude/usage-cost-api#usage-api) 追蹤 token 消耗量作為成本的替代指標。

## 另請參閱

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

* [Admin API](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api)
* [Admin API 參考文件](https://platform.claude.com/docs/zh-TW/api/beta/organization)
* [Analytics API](https://platform.claude.com/docs/zh-TW/manage-claude/analytics-api) - 您的組織需要哪一個分析 API 與金鑰類型
* [定價](https://platform.claude.com/docs/zh-TW/about-claude/pricing)
* [提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching) - 透過快取最佳化成本
* [批次處理](https://platform.claude.com/docs/zh-TW/build-with-claude/batch-processing) - 批次請求享 50% 折扣
* [速率限制](https://platform.claude.com/docs/zh-TW/api/rate-limits) - 了解用量層級
* [Rate Limits API](https://platform.claude.com/docs/zh-TW/manage-claude/rate-limits-api) - 讀取您已設定的速率限制
* [資料駐留](https://platform.claude.com/docs/zh-TW/manage-claude/data-residency) - 控制推論地理位置