Claude Agent SDK には、1 回のエージェント実行で消費したトークンを集計するためのフィールドが用意されています。本稿は、TypeScript SDK と Python SDK で同じ情報がどのフィールド名で、どの型のメッセージに現れるかを、実装者が読み替えられる粒度で突き合わせます。検証日は 2026-10-17 (JST)、出典はすべて公式ドキュメント 1 本です。
per-step（各ステップ）のトークン使用量
Claude の各 assistant メッセージには、そのステップのトークン内訳が付きます。TypeScript では message.message.usage、Python では message.usage から読めます (出典 [1])。per-model の集計は result メッセージの modelUsage に載ります。
Python の対応フィールドは AssistantMessage.usage と AssistantMessage.message_id（per-step 用）、per-model 集計は ResultMessage.model_usage です (出典 [1])。
output_tokens はプレースホルダー
per-step の output_tokens はプレースホルダーで、正確な出力トークン数は result メッセージから読む必要があります (出典 [1])。per-step で見える出力トークン数をそのまま合算してはいけません。
ID による重複排除
Claude が 1 ターンで複数のツールを並列使用すると、そのターンの全メッセージが同一の ID を共有します。ID で重複排除しないとトークンが二重カウントされます (出典 [1])。
all messages in that turn share the same ID, so deduplicate by ID to avoid double-counting
同一ターンのメッセージは同じ ID を持つので、ID で de-dup せよ、という意味です。
result メッセージの型
result メッセージの型は、TypeScript では SDKResultMessage、Python では ResultMessage です (出典 [1])。ここに実行全体の合計が集約されます。
modelUsage / model_usage はサブエージェントも数える
modelUsage（TS）/ model_usage（Python）は、トップレベルのループに加えてサブエージェントのリクエストもモデル別に数えます (出典 [1])。各エントリの costBasis は、そのモデルの最新リクエストをどの価格表で値付けしたか（list / managed / unknown）を示し、Claude Code v2.1.246 以降が必要です (出典 [1])。
コスト推定値の扱い
total_cost_usd と costUSD はクライアントサイドの推定値であり、権威ある請求データではありません (出典 [1])。
The total_cost_usd and costUSD fields are client-side estimates, not authoritative billing data.
Python では total_cost_usd はオプショナル型なので、読む前に None でないことを確認します (出典 [1])。
キャッシュトークンと TTL
cache_creation_input_tokens は新規キャッシュ作成に使われ標準入力トークンより高い料金、cache_read_input_tokens は既存キャッシュ読み出しで低い料金です (出典 [1])。Python の ResultMessage.usage dict では message.usage.get("cache_read_input_tokens", 0) でアクセスします (出典 [1])。
API キー認証時、または Amazon Bedrock・Google Cloud's Agent Platform・Microsoft Foundry・Claude Platform on AWS 上では、デフォルトのキャッシュ TTL は 5 分です (出典 [1])。ENABLE_PROMPT_CACHING_1H を設定すると書き込み TTL を 1 時間に延長できますが、1 時間 TTL の書き込みは 5 分 TTL より高い料金です (出典 [1])。
data residency pricing
レスポンスの usage が inference_geo: "us" を報告する場合、SDK はそのレスポンスのトークンのリスト価格を 1.1 倍します (出典 [1])。このサポートには TypeScript Agent SDK v0.3.239 以降、または Python Agent SDK v0.2.144 以降が必要です (出典 [1])。
セッションと予算のエッジケース
同一セッションを resume する呼び出しでは、以前のセッションの累計コストが result の total_cost_usd に含まれます (出典 [1])。streaming input mode では /clear・/reset・/new を送るたびに running total がリセットされ、query() 内でそれ以外にリセット要因はありません (出典 [1])。ただし Python SDK v0.2.137 以前は、リセット時に emit されるメッセージが iterator にドロップされていたため、アプリが送る /clear ターンを自力で数える必要があります (出典 [1])。
error_max_budget_usd のエラー結果では、usage は予算を超えたレスポンスを除外しますが、total_cost_usd と modelUsage はそれを含みます (出典 [1])。