Kosten und Nutzung nachverfolgen

​

Token-Nutzung verstehen

• TypeScript bietet Token-Aufschlüsselungen pro Schritt für jede Assistenten-Nachricht (message.message.id, message.message.usage), Kosten pro Modell über modelUsage in der Ergebnisnachricht sowie eine kumulierte Gesamtsumme in der Ergebnisnachricht.
• Python bietet Token-Aufschlüsselungen pro Schritt für jede Assistenten-Nachricht als message.usage und message.message_id, Kosten pro Modell über model_usage in der Ergebnisnachricht sowie die kumulierte Gesamtsumme in der Ergebnisnachricht als total_cost_usd.

• query()-Aufruf: ein Aufruf der query()-Funktion des SDK. Ein einzelner Aufruf kann mehrere Schritte umfassen: Claude antwortet, verwendet Tools, erhält Ergebnisse und antwortet erneut. Jeder Aufruf erzeugt am Ende eine result-Nachricht, außer im Streaming-Eingabemodus, in dem ein query()-Aufruf mehrere Benutzer-Turns umfasst und jeder Turn seine eigene result-Nachricht ausgibt.
• Schritt: ein einzelner Anfrage-/Antwort-Zyklus innerhalb eines query()-Aufrufs. Jeder Schritt erzeugt Assistenten-Nachrichten mit Token-Nutzung.
• Sitzung: eine Reihe von query()-Aufrufen, die über eine Sitzungs-ID mithilfe der Option resume verknüpft sind. Die Ergebnisse eines fortgesetzten Aufrufs geben die gesamten Ausgaben der Sitzung an, nicht nur die des jeweiligen Aufrufs. Unter Kosten über mehrere Aufrufe hinweg kumulieren erfahren Sie, wie die Summen übernommen werden.

​

Kosten im Streaming-Eingabemodus verfolgen

• usage: umfasst nur diesen Turn und darin nur die Hauptagentenschleife, nicht die Subagenten, die sie ausgeführt hat.
• total_cost_usd und modelUsage bzw. model_usage in Python: enthalten die laufende Gesamtsumme für den gesamten bisherigen Aufruf sowie alle Ausgaben, die wiederhergestellt wurden, als der Aufruf eine Sitzung fortgesetzt hat.

• Das eigene Ergebnis des /clear-Turns: umfasst nur das, was seit dem Zurücksetzen ausgeführt wurde, und enthält eine neue session_id.
• Jedes spätere Ergebnis: zählt ab diesem Zurücksetzen weiter.
• Das letzte Ergebnis vor jedem /clear: enthält die Gesamtsumme für die Turns seit dem vorherigen Zurücksetzen.

​

Die Gesamtkosten einer Abfrage ermitteln

• In Python ist das Feld als optional typisiert. Prüfen Sie daher, dass es nicht None ist, bevor Sie es auslesen.
• Sowohl Erfolgs- als auch Fehlerergebnisse enthalten es, allerdings kann das endgültige Ergebnis nach einem Sitzungsabsturz den Wert auf null gesetzt enthalten.

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "result") {
      console.log(`Total cost: $${message.total_cost_usd}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, it still carried total_cost_usd and the
  // branch above has already run; connection or process failures yield
  // no result message.
  console.error(`Session ended with an error: ${error}`);
}

from claude_agent_sdk import query, ResultMessage
import asyncio


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, ResultMessage):
                print(f"Total cost: ${message.total_cost_usd or 0}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the branch above has already run;
        # connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

​

Nutzung pro Schritt und pro Modell verfolgen

​

Nutzung pro Schritt verfolgen

import { query } from "@anthropic-ai/claude-agent-sdk";

const seenIds = new Set<string>();
let totalInputTokens = 0;
let resultOutputTokens = 0;

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant" && !message.parent_tool_use_id) {
      const msgId = message.message.id;

      // Parallel tool calls share the same ID, only count once
      if (!seenIds.has(msgId)) {
        seenIds.add(msgId);
        totalInputTokens += message.message.usage.input_tokens;
      }
    }
    if (message.type === "result") {
      // Per-step output_tokens is a placeholder; the result message
      // carries the accumulated output total.
      resultOutputTokens = message.usage.output_tokens;
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result, so the
  // input total below still reflects the steps that ran before the failure.
  console.error(`Session ended with an error: ${error}`);
}

console.log(`Steps: ${seenIds.size}`);
console.log(`Input tokens: ${totalInputTokens}`);
console.log(`Output tokens: ${resultOutputTokens}`);

​

Nutzung pro Modell aufschlüsseln

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type !== "result") continue;

    for (const [modelName, usage] of Object.entries(message.modelUsage)) {
      console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`);
      console.log(`  Input tokens: ${usage.inputTokens}`);
      console.log(`  Output tokens: ${usage.outputTokens}`);
      console.log(`  Cache read: ${usage.cacheReadInputTokens}`);
      console.log(`  Cache creation: ${usage.cacheCreationInputTokens}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the per-model breakdown above has already
  // printed; connection or process failures yield no result message.
  console.error(`Session ended with an error: ${error}`);
}

​

Kosten über mehrere Aufrufe hinweg akkumulieren

• Unabhängige Aufrufe ohne die Option resume oder continue: Jedes Ergebnis deckt nur den eigenen Aufruf ab, daher addieren Sie die Gesamtwerte selbst, wie es die folgenden Beispiele tun.
• Aufrufe, die dieselbe Sitzung fortsetzen: Claude Code speichert die Gesamtwerte der Sitzung in ihrem Transkript, wenn der Prozess normal beendet wird, und stellt sie wieder her, wenn ein späterer Aufruf die Sitzung fortsetzt oder forkt. Jedes Ergebnis enthält bereits die früheren Ausgaben der Sitzung. Lesen Sie das neueste Ergebnis, um den Gesamtwert der Sitzung zu erhalten; wenn Sie die Ergebnisse summieren, werden die wiederhergestellten Ausgaben doppelt gezählt. Vor v2.1.277 begannen die Gesamtwerte einer Sitzung, die Sie über das SDK oder claude -p fortgesetzt haben, bei null, sodass die Ergebnisse jedes Aufrufs nur diesen Aufruf abdeckten.

import { query } from "@anthropic-ai/claude-agent-sdk";

// Track cumulative cost across multiple query() calls
let totalSpend = 0;

const prompts = [
  "Read the files in src/ and summarize the architecture",
  "List all exported functions in src/auth.ts"
];

for (const prompt of prompts) {
  try {
    for await (const message of query({ prompt })) {
      if (message.type === "result") {
        totalSpend += message.total_cost_usd;
        console.log(`This call: $${message.total_cost_usd}`);
      }
    }
  } catch (error) {
    // A single-shot query() throws after yielding an error result. If the
    // failure was an error result, this call's cost was already counted;
    // connection or process failures yield no result message. Continue
    // with the next prompt.
    console.error(`Call failed: ${error}`);
  }
}

console.log(`Total spend: $${totalSpend.toFixed(4)}`);

from claude_agent_sdk import query, ResultMessage
import asyncio


async def main():
    # Track cumulative cost across multiple query() calls
    total_spend = 0.0

    prompts = [
        "Read the files in src/ and summarize the architecture",
        "List all exported functions in src/auth.ts",
    ]

    for prompt in prompts:
        try:
            async for message in query(prompt=prompt):
                if isinstance(message, ResultMessage):
                    cost = message.total_cost_usd or 0
                    total_spend += cost
                    print(f"This call: ${cost}")
        except Exception as error:
            # A single-shot query() raises after yielding an error result. If
            # the failure was an error result, this call's cost was already
            # counted; connection or process failures yield no result message.
            # Continue with the next prompt.
            print(f"Call failed: {error}")

    print(f"Total spend: ${total_spend:.4f}")


asyncio.run(main())

​

Fehler, Caching und Ausgabe-Token-Zählungen behandeln

​

Ausgabe-Token aus der Ergebnisnachricht lesen

​

Kosten bei fehlgeschlagenen Konversationen verfolgen

• error_during_execution nach einem Sitzungsabsturz: Alle Kostenfelder können auf null gesetzt sein.
• error_max_budget_usd: usage lässt die Antwort aus, die das Budget überschritten hat, während total_cost_usd und modelUsage sie enthalten.

​

Summen nach einem Sitzungsabsturz wiederherstellen

1. Verwenden Sie das Ergebnis des Turns vor dem Absturz. Im Streaming-Eingabemodus enthält es die laufende Summe, die unter Kosten im Streaming-Eingabemodus verfolgen beschrieben ist. Gehen Sie stattdessen zu Schritt 2, wenn Ihnen dieses Ergebnis nicht weiterhilft:
   • Der Aufruf war Single-Shot, daher existiert kein früheres Ergebnis.
   • Der Absturz trat im ersten Turn auf.
   • Der Turn vor dem Absturz war das /clear selbst, sodass sein Ergebnis nur das Zurücksetzen abdeckt.
2. Summieren Sie stattdessen usage der Assistentennachrichten und zählen Sie jede API-Antwort nur einmal, wie es das Beispiel unter Nutzung pro Schritt verfolgen tut. Im Single-Shot-Modus summieren Sie alle; im Streaming-Eingabemodus summieren Sie diejenigen, die nach dem letzten Ergebnis eingetroffen sind. Dadurch erhalten Sie die Eingabe- und Cache-Token der Hauptschleife. Die Nutzung von Subagenten lässt sich auf diese Weise nicht wiederherstellen, ebenso wenig Ausgabe-Token oder USD-Kosten, da output_tokens pro Schritt ein Platzhalter ist.

​

Cache-Token verfolgen

• cache_creation_input_tokens: Token, die zum Erstellen neuer Cache-Einträge verwendet werden (zu einem höheren Tarif abgerechnet als Standard-Eingabe-Token).
• cache_read_input_tokens: Token, die aus vorhandenen Cache-Einträgen gelesen werden (zu einem reduzierten Tarif abgerechnet).

​

Die TTL des Prompt-Caches auf eine Stunde verlängern

from claude_agent_sdk import ClaudeAgentOptions, query
import asyncio


async def main():
    options = ClaudeAgentOptions(
        env={
            "CLAUDE_CODE_USE_BEDROCK": "1",
            "ENABLE_PROMPT_CACHING_1H": "1",
        },
    )

    async for message in query(prompt="Summarize this project", options=options):
        print(message)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

const options = {
  env: {
    ...process.env,
    CLAUDE_CODE_USE_BEDROCK: "1",
    ENABLE_PROMPT_CACHING_1H: "1",
  },
};

for await (const message of query({ prompt: "Summarize this project", options })) {
  console.log(message);
}

• Hauptkonversation: die Umgebungsvariable CLAUDE_CODE_PROMPT_CACHE_TTL oder die Einstellung promptCacheTtl
• Alles andere: die Umgebungsvariable CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL oder die Einstellung subagentPromptCacheTtl

​

Verwandte Dokumentation

• TypeScript SDK Referenz - Vollständige API-Dokumentation
• SDK Übersicht - Erste Schritte mit dem SDK
• SDK Berechtigungen - Verwaltung von Tool-Berechtigungen