瞭解權杖使用量
TypeScript 和 Python SDK 使用不同的欄位名稱公開相同的使用量資料:- TypeScript 在每個助手訊息上提供逐步權杖細目(
message.message.id、message.message.usage),透過結果訊息上的modelUsage提供每個模型的成本,以及結果訊息上的累積總計。 - Python 在每個助手訊息上提供逐步權杖細目,分別為
message.usage和message.message_id,透過結果訊息上的model_usage提供每個模型的成本,以及結果訊息上的累積總計,名稱為total_cost_usd。
query()呼叫: SDK 的query()函式的一次調用。單一呼叫可能涉及多個步驟:Claude 回應、使用工具、取得結果,然後再次回應。每個呼叫在結尾產生一個result訊息,除了在串流輸入模式中,其中一個query()呼叫會進行多個使用者回合,每個回合會發出自己的result訊息。- 步驟:
query()呼叫內的單一請求/回應週期。每個步驟產生具有權杖使用量的助手訊息。 - 工作階段: 由工作階段 ID 連結的一系列
query()呼叫(使用resume選項)。已恢復呼叫的結果會報告工作階段的整體支出,而不只是該呼叫自己的支出。請參閱跨多個呼叫累積成本以瞭解總計如何結轉。
query() 呼叫的訊息串流,在每個步驟報告權杖使用量,以及結尾的累積估計:
1
每個步驟產生助手訊息
當 Claude 回應時,它會傳送一個或多個助手訊息。在 TypeScript 中,每個助手訊息包含一個巢狀的
BetaMessage(透過 message.message 存取),具有 id 和一個包含權杖計數(input_tokens、output_tokens)的 usage 物件。在 Python 中,AssistantMessage 資料類別透過 message.usage 和 message.message_id 直接公開相同的資料。當 Claude 在一個回合中使用多個工具時,該回合中的所有訊息共享相同的 ID,因此請按 ID 進行重複資料刪除以避免重複計算。2
結果訊息提供累積估計
當
query() 呼叫完成時,SDK 會發出一個結果訊息,其中包含 total_cost_usd 和累積 usage,在 TypeScript 中輸入為 SDKResultMessage,在 Python 中輸入為 ResultMessage。如果您只需要估計的總計,您可以忽略逐步使用量,並讀取此單一值。如果您進行多個獨立的 query() 呼叫,每個結果只反映該個別呼叫的成本。恢復工作階段的呼叫也會計算工作階段的較早支出。在串流輸入模式中,每個回合會發出自己的結果訊息。請參閱在串流輸入模式中追蹤成本以瞭解如何在該模式中讀取呼叫總計。在串流輸入模式中追蹤成本
在串流輸入模式中,一個query() 呼叫會進行多個使用者回合,每個回合都會發出自己的結果訊息。結果欄位的範圍不同:
usage:僅涵蓋該回合,且在其中僅涵蓋主代理迴圈,不包括它執行的任何子代理。total_cost_usd和modelUsage,或 Python 中的model_usage:攜帶迄今為止整個呼叫的執行總計,加上呼叫恢復工作階段時復原的任何支出。
/clear、/reset 或 /new 的呼叫中,讀取最新結果以取得呼叫總計,而不是跨結果求和。
執行總計在您的應用程式每次傳送這三個命令之一時重新開始,在 query() 呼叫內,沒有其他東西會重設它們。三個結果對您的會計很重要:
/clear回合自己的結果:僅涵蓋自重設以來執行的內容,並攜帶新的session_id。- 之後的每個結果:從該重設開始繼續計數。
- 每個
/clear之前的最後結果:保持自上一次重設以來的回合總計。
/clear 之前的最後結果加上呼叫的最終結果。所有其他結果(包括 /clear 回合自己的結果)都被後續結果取代。
在 TypeScript 中,SDK 也會在每次重設時發出 SDKConversationResetMessage,因此您可以從串流中偵測重設。在 Python 中,SDK 同樣會發出 ConversationResetMessage。在 Python SDK v0.2.137 之前,Python 迭代器會捨棄該訊息,因此在這些版本上,請從您的應用程式傳送的 /clear 回合自行計數重設。
maxBudgetUsd(TypeScript)或 max_budget_usd(Python)僅計算呼叫自身的支出:從恢復的工作階段復原的總計不計入其中,/clear 會重新開始預算。
取得查詢的總成本
結果訊息在 TypeScript 中被型別化為SDKResultMessage,在 Python 中被型別化為 ResultMessage,標記了 query() 呼叫的代理程式迴圈結束。它包含 total_cost_usd,即該呼叫中所有步驟的累積估計成本。恢復工作階段的呼叫也會計算工作階段的早期支出。讀取該值時適用兩項注意事項:
- 在 Python 中,該欄位被型別化為選用的,因此在讀取之前請檢查它不是
None。 - 成功和錯誤結果都會帶有它,儘管工作階段當機的最終結果可能會帶有零值。
modelUsage,或在 Python 中使用 model_usage,進行整個樹狀結構的權杖計算;usage 欄位一旦發生巢狀就會低估。
在單一訊息輸入模式中,當背景子代理程式在最後一個回合結束時仍在執行時,Claude Code 會等待它們,直到在結束時的背景工作中描述的上限,然後才發出結果。結果的
total_cost_usd、duration_api_ms 和 modelUsage,或在 Python 中的 model_usage,包括在該等待期間完成的工作。
以下範例會逐一查看來自 query() 呼叫的訊息串流,並在 result 訊息到達時列印總成本:
total_cost_usd 的金額,請在查詢上設定深度、並行性和支出限制。
追蹤每個步驟和每個模型的使用情況
本節中的範例使用 TypeScript 欄位名稱。在 Python 中,對應的欄位是AssistantMessage.usage 和 AssistantMessage.message_id 用於每個步驟的使用情況,以及 ResultMessage.model_usage 用於每個模型的細目。
追蹤每個步驟的使用情況
每個助手訊息都包含一個巢狀的BetaMessage(透過 message.message 存取),其中包含 id 和具有權杖計數的 usage 物件。當 Claude 並行使用工具時,多個訊息共享相同的 id 和相同的使用資料。追蹤您已經計算過的 ID,並跳過重複項以避免總數膨脹。
以下範例累積所有步驟中的輸入權杖,只計算一次每個唯一的主迴圈訊息 ID 並跳過子代理訊息,並從結果訊息讀取輸出總計,該訊息涵蓋主迴圈:
按模型細分使用情況
結果訊息包含modelUsage,這是模型名稱到每個模型權杖計數和成本的對應。當您執行多個模型(例如,子代理使用 Haiku,主代理使用 Opus)並想查看權杖流向何處時,這很有用。
每個項目的 costBasis 說明哪個價格表為該模型的最新請求定價:list 表示清單價格,managed 表示 modelPricing 表,或 unknown 表示兩者都不符合模型 ID。該欄位需要 Claude Code v2.1.246 或更新版本。
以下範例執行查詢並列印每個使用的模型的成本和權杖細目:
累積多次呼叫的成本
每個query() 呼叫都會在其結果上傳回 total_cost_usd。您如何合併這些值取決於呼叫是否共享工作階段:
- 獨立呼叫,沒有
resume或continue選項:每個結果只涵蓋其自己的呼叫,因此請自行加總,如下面的範例所示。 - 恢復相同工作階段的呼叫:Claude Code 會在程序正常退出時將工作階段的總計儲存到其文字記錄,並在稍後的呼叫恢復或分叉工作階段時復原它們。每個結果已經包含工作階段的早期支出。讀取工作階段的最新結果以取得工作階段總計;加總結果會重複計算已復原的支出。在 v2.1.277 之前,您透過 SDK 或
claude -p恢復的工作階段會將其總計從零開始,因此每個呼叫的結果只涵蓋該呼叫。
query() 呼叫,將每個呼叫的 total_cost_usd 加入執行中的總計,並列印每次呼叫和合併的成本:
處理錯誤、快取和輸出 token 計數
為了準確追蹤成本,需要考慮助手訊息上的預留位置輸出計數、失敗對話消耗的 token,以及快取 token 定價。從結果訊息讀取輸出 token
Claude Code 從 API 在回應開始時報告的使用量建立每個助手訊息,因此訊息的output_tokens 只是 API 在 message_start 時報告的計數,在回應生成之前。一個 API 回應可以產生多個助手訊息,每一個都帶有相同的預留位置。
API 在回應結束時報告實際輸出計數,Claude Code 將其新增到結果訊息。從結果的 usage 讀取輸出 token,或從 modelUsage 讀取每個模型的細目。
若要在串流時監看回應的輸出計數增長,請設定 includePartialMessages,或在 Python 中設定 include_partial_messages,並從每個 message_delta 串流事件讀取 usage,在 TypeScript 中型別為 SDKPartialAssistantMessage,在 Python 中型別為 StreamEvent。
追蹤失敗對話的成本
成功和錯誤結果訊息都包含usage 和 total_cost_usd;在 Python 中兩個欄位都型別為選用,因此在讀取之前請檢查它們不是 None。
如果對話在中途失敗,您仍然消耗了到失敗點為止的 token。從每個結果訊息讀取成本資料,無論其 subtype 是 success 還是其中一個錯誤子型別。在某些錯誤結果上,usage 報告的少於呼叫花費的:
error_during_execution在 工作階段當機 之後:每個成本欄位可能被清零。error_max_budget_usd:usage遺漏了超過預算的回應,而total_cost_usd和modelUsage包含它。
total_cost_usd 或 modelUsage 而不是 usage 進行計帳。
在工作階段當機後復原總計
當 Claude Code 程序當機時,它會發出最終的error_during_execution 結果並退出,在單次和串流輸入模式中都是如此。該結果可能帶有清零的 usage、total_cost_usd 和 modelUsage,因此從它之前到達的內容復原呼叫的總計。步驟 1 在存在較早結果時復原完整總計;步驟 2 中的備用方案只復原主迴圈的輸入和快取 token。
- 使用當機前轉換的結果。在串流輸入模式中,它保持自呼叫開始或自上次
/clear以來的執行總計。當該結果無法幫助您時,改為進行步驟 2:- 呼叫是單次的,因此不存在較早的結果。
- 當機發生在第一個轉換上。
- 當機前的轉換是
/clear本身,因此其結果只涵蓋重設。
- 改為對助手訊息上的
usage求和,計算每個 API 回應一次,如 追蹤每步驟使用量 範例所做。在單次模式中,對所有進行求和;在串流輸入模式中,對最後一個結果之後到達的進行求和。這給您主迴圈的輸入和快取 token。子代理使用量無法以這種方式復原,輸出 token 或美元成本也無法,因為 每步驟output_tokens是預留位置。
追蹤快取 token
Agent SDK 自動使用 prompt caching 來降低重複內容的成本。您不需要自己設定快取。使用量物件包含兩個額外的欄位用於快取追蹤:cache_creation_input_tokens:用於建立新快取項目的 token(以高於標準輸入 token 的費率計費)。cache_read_input_tokens:從現有快取項目讀取的 token(以降低的費率計費)。
input_tokens 分開追蹤,以了解快取節省。在 TypeScript 中,這些欄位在 Usage 物件上型別化。在 Python 中,它們作為 ResultMessage.usage 字典中的鍵出現(例如,message.usage.get("cache_read_input_tokens", 0))。
將 prompt 快取 TTL 延長至一小時
您自己的轉換落在 主對話 TTL 值區 中,與 Claude Code 與它們內聯執行的協助程式一起。Claude Code 在該對話之外進行的請求,例如 子代理,有 單獨的 TTL 控制。 當您使用 API 金鑰進行驗證或在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上執行時,您自己的轉換的快取項目預設使用 5 分鐘 TTL。如果您的工作負載針對相同的系統提示和內容執行許多短工作階段,且它們之間的間隔超過 5 分鐘,快取會在工作階段之間過期,每個新工作階段都支付完整輸入價格。 若要在快取寫入上請求 1 小時 TTL,請設定ENABLE_PROMPT_CACHING_1H 環境變數。您可以在您的 shell 或容器環境中匯出它,或通過 options.env 傳遞它。
以下範例為在 Amazon Bedrock 上執行的代理啟用 1 小時 TTL。因為它設定了 CLAUDE_CODE_USE_BEDROCK,它需要 Amazon Bedrock 的有效 AWS 認證;沒有它們查詢會失敗。
ENABLE_PROMPT_CACHING_1H 要求在兩個值區中的每個請求上使用 1 小時 TTL。若要為每個值區分別選擇 TTL,請改為使用這些控制。每個採用 5m 或 1h 並優先於 ENABLE_PROMPT_CACHING_1H:
- 主對話:
CLAUDE_CODE_PROMPT_CACHE_TTL環境變數,或promptCacheTtl設定 - 其他所有內容:
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL環境變數,或subagentPromptCacheTtl設定
promptCacheTtl 設定為 1h 會在您使用使用量點數時保持主對話上的 1 小時快取。有關完整優先順序,請參閱 選擇 TTL。
相關文件
- TypeScript SDK 參考 - 完整的 API 文件
- SDK 概述 - SDK 入門
- SDK 權限 - 管理工具權限