Suivre les coûts et l'utilisation

​

Comprendre l’utilisation des tokens

• TypeScript fournit des ventilations de tokens par étape sur chaque message d’assistant (message.message.id, message.message.usage), le coût par modèle via modelUsage sur le message de résultat, et un total cumulatif sur le message de résultat.
• Python fournit des ventilations de tokens par étape sur chaque message d’assistant en tant que message.usage et message.message_id, le coût par modèle via model_usage sur le message de résultat, et le total cumulatif sur le message de résultat en tant que total_cost_usd.

• Appel query() : une invocation de la fonction query() du SDK. Un seul appel peut impliquer plusieurs étapes : Claude répond, utilise des outils, obtient des résultats et répond à nouveau. Chaque appel produit un message result à la fin, sauf en mode d’entrée en streaming, où un appel query() porte plusieurs tours d’utilisateur et chaque tour émet son propre message result.
• Étape : un seul cycle requête/réponse au sein d’un appel query(). Chaque étape produit des messages d’assistant avec l’utilisation des tokens.
• Session : une série d’appels query() liés par un ID de session via l’option resume. Les résultats d’un appel repris rapportent la dépense totale de la session, pas seulement celle de cet appel. Consultez Accumuler les coûts sur plusieurs appels pour voir comment les totaux se reportent.

​

Suivre les coûts en mode d’entrée en continu

• usage : couvre uniquement ce tour, et au sein de celui-ci uniquement la boucle principale de l’agent, pas les sous-agents qu’il a exécutés.
• total_cost_usd et modelUsage, ou model_usage en Python : portent le total cumulé pour l’ensemble de l’appel jusqu’à présent, plus toute dépense restaurée lorsque l’appel a repris une session.

• Le propre résultat du tour /clear : couvre uniquement ce qui s’est exécuté depuis la réinitialisation, et porte un nouveau session_id.
• Chaque résultat ultérieur : continue à compter à partir de cette réinitialisation.
• Le dernier résultat avant chaque /clear : contient le total pour les tours depuis la réinitialisation précédente.

​

Obtenir le coût total d’une requête

• En Python, le champ est typé comme optionnel, donc vérifiez qu’il n’est pas None avant de le lire.
• Les résultats de succès et d’erreur le portent tous les deux, bien que le résultat final d’un plantage de session peut le porter à zéro.

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())

​

Suivre l’utilisation par étape et par modèle

​

Suivre l’utilisation par étape

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}`);

​

Ventiler l’utilisation par modèle

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}`);
}

​

Accumuler les coûts sur plusieurs appels

• Appels indépendants, sans option resume ou continue : chaque résultat couvre uniquement son propre appel, donc additionnez les totaux vous-même, comme le font les exemples ci-dessous.
• Appels qui reprennent la même session : Claude Code enregistre les totaux de la session dans sa transcription lorsque le processus se termine normalement et les restaure lorsqu’un appel ultérieur reprend ou crée une branche de la session. Chaque résultat inclut déjà les dépenses antérieures de la session. Lisez le dernier résultat pour le total de la session ; additionner les résultats double-compte les dépenses restaurées. Avant v2.1.277, une session que vous aviez reprise via le SDK ou claude -p commençait ses totaux à zéro, donc chaque appel couvrait uniquement cet appel.

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())

​

Gérer les erreurs, la mise en cache et les comptages de jetons de sortie

​

Lire les jetons de sortie du message de résultat

​

Suivre les coûts sur les conversations échouées

• error_during_execution après un plantage de session : chaque champ de coût peut être mis à zéro.
• error_max_budget_usd : usage omet la réponse qui a dépassé le budget, tandis que total_cost_usd et modelUsage l’incluent.

​

Récupérer les totaux après un plantage de session

1. Utilisez le résultat du tour avant le plantage. En mode d’entrée en continu, il contient le total cumulé décrit dans Suivre les coûts en mode d’entrée en continu. Allez à l’étape 2 à la place lorsque ce résultat ne peut pas vous aider :
   • L’appel était unique, donc aucun résultat antérieur n’existe.
   • Le plantage s’est produit au premier tour.
   • Le tour avant le plantage était le /clear lui-même, donc son résultat couvre uniquement la réinitialisation.
2. Additionnez plutôt le usage sur les messages d’assistant, en comptant chaque réponse API une fois, comme l’exemple Track per-step usage le fait. En mode unique, additionnez-les tous ; en mode d’entrée en continu, additionnez ceux qui sont arrivés après le dernier résultat. Cela vous donne les jetons d’entrée et de cache de la boucle principale. L’utilisation des sous-agents n’est pas récupérable de cette façon, pas plus que les jetons de sortie ou le coût en USD, car le output_tokens par étape est un placeholder.

​

Suivre les jetons en cache

• cache_creation_input_tokens : jetons utilisés pour créer de nouvelles entrées de cache (facturés à un taux plus élevé que les jetons d’entrée standard).
• cache_read_input_tokens : jetons lus à partir des entrées de cache existantes (facturés à un taux réduit).

​

Étendre le TTL du cache d’invite à une heure

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);
}

• Conversation principale : la variable d’environnement CLAUDE_CODE_PROMPT_CACHE_TTL, ou le paramètre promptCacheTtl
• Tout le reste : la variable d’environnement CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, ou le paramètre subagentPromptCacheTtl

​

Documentation connexe

• Référence du SDK TypeScript - Documentation complète de l’API
• Aperçu du SDK - Prise en main du SDK
• Permissions du SDK - Gestion des permissions des outils