5 ファイル変更 +19 -11
この更新の概要
Claude Agent SDKおよびCLIツールにおけるコスト計算の定義が、確定値からクライアントサイドでの「見積もり値」へと修正されました。SDKがビルド時に持つ価格テーブルを元にローカルで計算を行うため、実際の請求額とは異なる可能性があることが明記されています。正確な請求データを確認するための手段として、Usage and Cost APIやClaude Consoleの参照を推奨するガイダンスが追加されました。全体として、開発時の予算目安としての利用に留め、エンドユーザーへの請求根拠にしないよう注意を促す内容となっています。
SDKによるコスト計算はローカルでの見積もりであり、価格改定や未対応モデルの使用により実際の請求額とズレが生じる可能性がある旨の警告が追加されました。開発時の洞察や予算案としてのみ利用し、金融上の決定やエンドユーザーへの請求には使用しないようガイドラインが更新されています。
@@ -5,12 +5,20 @@ source: https://code.claude.com/docs/en/agent-sdk/cost-tracking.md
# Track cost and usage
> Learn how to track token usage, deduplicate parallel tool calls, and calculate costs with the Claude Agent SDK.
> Learn how to track token usage, deduplicate parallel tool calls, and estimate costs with the Claude Agent SDK.
The Claude Agent SDK provides detailed token usage information for each interaction with Claude. This guide explains how to properly track costs and understand usage reporting, especially when dealing with parallel tool uses and multi-step conversations.
The Claude Agent SDK provides detailed token usage information for each interaction with Claude. This guide explains how to properly track usage and understand cost reporting, especially when dealing with parallel tool uses and multi-step conversations.
For complete API documentation, see the [TypeScript SDK reference](/en/agent-sdk/typescript) and [Python SDK reference](/en/agent-sdk/python).
The `total_cost_usd` and `costUSD` fields are client-side estimates, not authoritative billing data. The SDK computes them locally from a price table bundled at build time, so they can drift from what you are actually billed when:
- pricing changes
- the installed SDK version does not recognize a model
- billing rules apply that the client cannot model
Use these fields for development insight and approximate budgeting. For authoritative billing, use the [Usage and Cost API](https://platform.claude.com/docs/en/build-with-claude/usage-cost-api) or the Usage page in the [Claude Console](https://platform.claude.com/usage). Do not bill end users or trigger financial decisions from these fields.
## Understand token usage
The TypeScript and Python SDKs expose the same usage data with different field names:
@@ -26,11 +34,11 @@ Cost tracking depends on understanding how the SDK scopes usage data:
- **Step:** a single request/response cycle within a `query()` call. Each step produces assistant messages with token usage.
- **Session:** a series of `query()` calls linked by a session ID (using the `resume` option). Each `query()` call within a session reports its own cost independently.
The following diagram shows the message stream from a single `query()` call, with token usage reported at each step and the authoritative total at the end:
The following diagram shows the message stream from a single `query()` call, with token usage reported at each step and the cumulative estimate at the end:
When Claude responds, it sends one or more assistant messages. In TypeScript, each assistant message contains a nested `BetaMessage` (accessed via `message.message`) with an `id` and a [`usage`](https://platform.claude.com/docs/en/api/messages) object with token counts (`input_tokens`, `output_tokens`). In Python, the `AssistantMessage` dataclass exposes the same data directly via `message.usage` and `message.message_id`. When Claude uses multiple tools in one turn, all messages in that turn share the same ID, so deduplicate by ID to avoid double-counting.
When the `query()` call completes, the SDK emits a result message with `total_cost_usd` and cumulative `usage`. This is available in both TypeScript ([`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message)) and Python ([`ResultMessage`](/en/agent-sdk/python#result-message)). If you make multiple `query()` calls (for example, in a multi-turn session), each result only reflects the cost of that individual call. If you only need the total cost, you can ignore the per-step usage and read this single value.
When the `query()` call completes, the SDK emits a result message with `total_cost_usd` and cumulative `usage`. This is available in both TypeScript ([`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message)) and Python ([`ResultMessage`](/en/agent-sdk/python#result-message)). If you make multiple `query()` calls (for example, in a multi-turn session), each result only reflects the cost of that individual call. If you only need the estimated total, you can ignore the per-step usage and read this single value.
## Get the total cost of a query
@@ -182,7 +190,7 @@ For accurate cost tracking, account for failed conversations, cache token pricin
In rare cases, you might observe different `output_tokens` values for messages with the same ID. When this occurs:
1. **Use the highest value:** the final message in a group typically contains the accurate total.
2. **Verify against total cost:** the `total_cost_usd` in the result message is authoritative.
2. **Prefer the result message:** the `total_cost_usd` in the result message reflects the SDK's accumulated estimate across all steps, so it is more reliable than summing per-step values yourself. It is still an estimate and may differ from your actual bill.
3. **Report inconsistencies:** file issues at the [Claude Code GitHub repository](https://github.com/anthropics/claude-code/issues).
### Track costs on failed conversations
@@ -1426,7 +1426,7 @@ The `model_usage` dict maps model names to per-model usage. The inner dict keys
| `cacheReadInputTokens` | `int` | Cache read tokens for this model. |
| `cacheCreationInputTokens` | `int` | Cache creation tokens for this model. |
| `webSearchRequests` | `int` | Web search requests made by this model. |
| `costUSD` | `float` | Cost in USD for this model. |
| `costUSD` | `float` | Estimated cost in USD for this model, computed client-side. See [Track cost and usage](/en/agent-sdk/cost-tracking) for billing caveats. |
| `contextWindow` | `int` | Context window size for this model. |
| `maxOutputTokens` | `int` | Maximum output token limit for this model. |
@@ -2183,7 +2183,7 @@ Documentation of input/output schemas for all built-in Claude Code tools. While
{
"result": str, # Final result from the subagent
"usage": dict | None, # Token usage statistics
"total_cost_usd": float | None, # Total cost in USD
"total_cost_usd": float | None, # Estimated total cost in USD
"duration_ms": int | None, # Execution duration in milliseconds
}
```
TypeScript SDKのモデル別使用統計において、costUSDがクライアントサイドの見積もりであることを明記し、コスト追跡に関する注意事項へのリンクが追加されました。
@@ -2263,7 +2263,7 @@ type AccountInfo = {
### `ModelUsage`
Per-model usage statistics returned in result messages.
Per-model usage statistics returned in result messages. The `costUSD` value is a client-side estimate. See [Track cost and usage](/en/agent-sdk/cost-tracking) for billing caveats.
```typescript
type ModelUsage = {
/costコマンドで表示されるドル表記の金額が、トークン数からローカルで計算された見積もりであり、公式な請求額はClaude Consoleで確認すべきであることが明記されました。
@@ -19,7 +19,7 @@ This page covers how to [track your costs](#track-your-costs), [manage costs for
The `/cost` command shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so `/cost` data isn't relevant for billing purposes. Subscribers can use `/stats` to view usage patterns.
The `/cost` command provides detailed token usage statistics for your current session:
The `/cost` command provides detailed token usage statistics for your current session. The dollar figure is an estimate computed locally from token counts and may differ from your actual bill. For authoritative billing, see the Usage page in the [Claude Console](https://platform.claude.com/usage).
```text
Total cost: $0.55
@@ -140,7 +140,7 @@ Claude Code sends the following JSON fields to your script via stdin:
| `workspace.project_dir` | Directory where Claude Code was launched, which may differ from `cwd` if the working directory changes during a session |
| `workspace.added_dirs` | Additional directories added via `/add-dir` or `--add-dir`. Empty array if none have been added |
| `workspace.git_worktree` | Git worktree name when the current directory is inside a linked worktree created with `git worktree add`. Absent in the main working tree. Populated for any git worktree, unlike `worktree.*` which applies only to `--worktree` sessions |
| `cost.total_cost_usd` | Total session cost in USD |
| `cost.total_cost_usd` | Estimated session cost in USD, computed client-side. May differ from your actual bill |
| `cost.total_duration_ms` | Total wall-clock time since the session started, in milliseconds |
| `cost.total_api_duration_ms` | Total time spent waiting for API responses in milliseconds |
| `cost.total_lines_added`, `cost.total_lines_removed` | Lines of code changed |
@@ -431,7 +431,7 @@ process.stdin.on('end', () => {
### Cost and duration tracking
Track your session's API costs and elapsed time. The `cost.total_cost_usd` field accumulates the cost of all API calls in the current session. The `cost.total_duration_ms` field measures total elapsed time since the session started, while `cost.total_api_duration_ms` tracks only the time spent waiting for API responses.
Track your session's API costs and elapsed time. The `cost.total_cost_usd` field accumulates the estimated cost of all API calls in the current session. The `cost.total_duration_ms` field measures total elapsed time since the session started, while `cost.total_api_duration_ms` tracks only the time spent waiting for API responses.
Each script formats cost as currency and converts milliseconds to minutes and seconds: