Rastrear custo e uso

​

Entender o uso de tokens

• TypeScript fornece detalhamentos de tokens por etapa em cada mensagem do assistente (message.message.id, message.message.usage), custo por modelo via modelUsage na mensagem de resultado, e um total cumulativo na mensagem de resultado.
• Python fornece detalhamentos de tokens por etapa em cada mensagem do assistente como message.usage e message.message_id, custo por modelo via model_usage na mensagem de resultado, e o total cumulativo na mensagem de resultado como total_cost_usd.

• Chamada query(): uma invocação da função query() do SDK. Uma única chamada pode envolver múltiplas etapas: Claude responde, usa ferramentas, obtém resultados e responde novamente. Cada chamada produz uma mensagem result ao final, exceto no modo de entrada em streaming, onde uma chamada query() carrega múltiplos turnos do usuário e cada turno emite sua própria mensagem result.
• Etapa: um único ciclo de solicitação/resposta dentro de uma chamada query(). Cada etapa produz mensagens do assistente com uso de tokens.
• Sessão: uma série de chamadas query() vinculadas por um ID de sessão através da opção resume. Uma chamada retomada relata o gasto total da sessão, não apenas o da própria chamada. Veja Acumular custos em múltiplas chamadas para saber como os totais se transferem.

​

Rastrear custos no modo de entrada em streaming

• usage: cobre apenas esse turno, e dentro dele apenas o loop principal do agente, não qualquer subagenteque ele executou.
• total_cost_usd e modelUsage, ou model_usage em Python: carregam o total acumulado para toda a chamada até agora, mais qualquer gasto restaurado quando a chamada retomou uma sessão.

• O resultado do próprio turno /clear: cobre apenas o que foi executado desde a redefinição, e carrega um novo session_id.
• Cada resultado posterior: continua contando a partir dessa redefinição.
• O último resultado antes de cada /clear: contém o total para os turnos desde a redefinição anterior.

​

Obter o custo total de uma consulta

• Em Python, o campo é digitado como opcional, portanto verifique se não é None antes de lê-lo.
• Os resultados de sucesso e erro carregam ambos, embora o resultado final de um travamento de sessão possa carregá-lo zerado.

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

​

Rastrear uso por etapa e por modelo

​

Rastrear uso por etapa

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

​

Detalhamento de uso por modelo

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

​

Acumular custos em múltiplas chamadas

• Chamadas independentes, sem opção resume ou continue: cada resultado cobre apenas sua própria chamada, portanto, adicione os totais você mesmo, como os exemplos abaixo fazem.
• Chamadas que retomam a mesma sessão: Claude Code salva os totais da sessão em sua transcrição quando o processo sai normalmente e os restaura quando uma chamada posterior retoma ou bifurca a sessão. Cada resultado já inclui o gasto anterior da sessão. Leia o resultado mais recente para o total da sessão; somar resultados conta duas vezes o gasto restaurado. Antes da v2.1.277, uma sessão que você retomou através do SDK ou claude -p iniciava seus totais em zero, portanto, cada resultado de chamada cobria apenas essa chamada.

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

​

Lidar com erros, cache e contagens de tokens de saída

​

Ler tokens de saída da mensagem de resultado

​

Rastrear custos em conversas falhadas

• error_during_execution após um travamento de sessão: cada campo de custo pode ser zerado.
• error_max_budget_usd: usage deixa de fora a resposta que ultrapassou o orçamento, enquanto total_cost_usd e modelUsage a incluem.

​

Recuperar totais após um travamento de sessão

1. Use o resultado da rodada antes do travamento. No modo de entrada de transmissão, ele contém o total em execução descrito em Rastrear custos no modo de entrada de transmissão. Vá para a etapa 2 em vez disso quando esse resultado não puder ajudá-lo:
   • A chamada foi única, portanto, nenhum resultado anterior existe.
   • O travamento aconteceu na primeira rodada.
   • A rodada antes do travamento foi o /clear em si, portanto, seu resultado cobre apenas a redefinição.
2. Some o usage nas mensagens do assistente em vez disso, contando cada resposta da API uma vez, como o exemplo Track per-step usage faz. No modo de entrada única, some todas elas; no modo de entrada de transmissão, some as que chegaram após o último resultado. Isso fornece os tokens de entrada e cache do loop principal. O uso de subagentos não é recuperável dessa forma, e nem são tokens de saída ou custo em USD, porque o output_tokens por etapa é um espaço reservado.

​

Rastrear tokens de cache

• cache_creation_input_tokens: tokens usados para criar novas entradas de cache (cobrados a uma taxa mais alta do que tokens de entrada padrão).
• cache_read_input_tokens: tokens lidos de entradas de cache existentes (cobrados a uma taxa reduzida).

​

Estender o TTL do cache de prompt para uma hora

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

• Conversa principal: a variável de ambiente CLAUDE_CODE_PROMPT_CACHE_TTL, ou a configuração promptCacheTtl
• Tudo mais: a variável de ambiente CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, ou a configuração subagentPromptCacheTtl

​

Documentação relacionada

• Referência do SDK TypeScript - Documentação completa da API
• Visão geral do SDK - Começando com o SDK
• Permissões do SDK - Gerenciando permissões de ferramentas