Para onde estão indo seus tokens? Como auditar o gasto de uma tarefa no Claude Code e na API

Dica de economia de token sem número na frente é chute com cara de conselho

A conta sobe, alguém sugere "escrever prompts menores", e ninguém sabe dizer de onde veio o consumo: se foi entrada, se foi saída, se foi cache mal aproveitado ou se foi o histórico da conversa sendo arrastado por 40 turnos

A ordem certa é o contrário do que costuma acontecer: primeiro tu descobre para onde o token está indo, depois tu corta o que realmente pesa

Então bora abrir as três camadas onde esse número está visível: o Claude Code no terminal, a resposta crua da API e a visão de organização no Console

O que você precisa antes de começar a auditoria

Cada camada de auditoria pede um acesso diferente, e é comum a pessoa travar no meio porque tentou rodar o passo de organização com a chave errada

Separa assim antes de começar:

• Claude Code instalado e uma sessão rodando: é o que te dá /usage e /context. Ressalva importante: a atribuição do uso por skills, subagents, plugins e servidores MCP individuais aparece nos planos Pro, Max, Team ou Enterprise
• Chave de API padrão: serve pra ler o bloco usage que volta em cada resposta e pra chamar o endpoint de contagem de tokens
• Admin API key: é uma chave diferente da padrão, com prefixo sk-ant-admin, provisionada no Claude Console só por um membro com papel admin. Sem ela, os endpoints de usage report e cost report não abrem
• Atenção ao ambiente: esses endpoints programáticos de Usage e Cost não estão disponíveis no Claude Platform on AWS

Se tu não tem a Admin API key, beleza: os passos que rodam no Claude Code e os que rodam com a chave padrão seguem valendo, só a visão de organização fica de fora

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Passo a passo: como auditar o gasto de tokens de uma tarefa

A sequência vai do mais barato (um comando no terminal) pro mais trabalhoso (chamada autenticada de organização)

Roda na ordem e para quando a resposta aparecer, não precisa ir até o fim sempre

1. Rode /usage dentro do Claude Code e leia o bloco Session

/usage

O bloco Session mostra o uso de tokens da API e as estatísticas detalhadas de token da sessão atual

Dentro dele tu alterna a janela de análise: d mostra as últimas 24 horas, w mostra os últimos 7 dias

Repara também nas flags de comportamento: long context e cache misses acendem quando um deles responde por 10% ou mais do uso recente

E, nos planos Pro, Max, Team ou Enterprise, tem a parte mais útil de todas: a atribuição do uso recente por skills, subagents, plugins e servidores MCP individuais, cada um como percentual do total

O erro comum deste passo: tratar o valor em dólar do CLI como fatura. Ele é calculado localmente a partir das contagens de token, com preços de tabela padrão. Pra faturamento autoritativo, a referência é a página Usage no Claude Console

2. Rode /context quando a conversa estiver longa

/context

Esse comando mostra o que está ocupando a janela de contexto

É o raio-x do "contexto arrastado": aquilo que entra de novo em toda requisição sem ninguém pedir

O erro comum deste passo: sair rodando /compact de cara. O /compact resume a conversa pra liberar espaço na janela, e isso é ótimo, mas se tu comprime antes de olhar, tu perde a única chance de saber QUEM estava ocupando o espaço

Olha primeiro, comprime depois

3. Leia o bloco usage da resposta da API

A resposta da API traz o uso separado em quatro campos, e cada um conta uma história diferente:

O total de entrada da requisição é a soma dos três campos de entrada:

total de entrada = input_tokens + cache_creation_input_tokens + cache_read_input_tokens

E os dois campos de cache não custam o mesmo que a entrada padrão: criação de cache é cobrada a uma taxa maior, leitura de cache a uma taxa reduzida

O erro comum deste passo: somar só input_tokens e achar que a conta fecha. Não fecha, e o buraco costuma estar exatamente no cache

A saída também merece atenção, porque output_tokens é o que a IA gerou, não o que tu escreveu. Quem acompanhou a discussão sobre o raciocínio estendido do Claude já tem uma intuição de por que resposta longa não é detalhe de estilo, é linha do consumo

4. Estime antes de executar com o count_tokens

Dá pra contar os tokens de uma mensagem ANTES de mandar ela pra inferência, incluindo tools, imagens e documentos:

curl -X POST https://api.anthropic.com/v1/messages/count_tokens \
  -H "content-type: application/json" \
  -d '{
    "model": "<o mesmo model id que você vai usar na inferência>",
    "messages": [
      { "role": "user", "content": "sua mensagem aqui" }
    ]
  }'

Os headers de autenticação e de versão da API são os mesmos que tu já manda nas chamadas normais de mensagens, então reaproveita o que já está no teu cliente

O erro comum deste passo: passar um model ID diferente do que vai rodar de verdade. A contagem é específica por modelo, então o número só vale se o model bater

E tem o clássico: tentar contar token de modelo Claude com tiktoken. A recomendação é não fazer isso

5. Suba pra visão de organização

Quando a pergunta deixa de ser "essa tarefa" e vira "o time inteiro", existem dois endpoints separados

O de uso:

GET /v1/organizations/usage_report/messages

Ele trabalha com buckets de tempo fixos (1m, 1h ou 1d), quebra os dados por modelo, workspace e service tier, e separa entrada não cacheada, entrada cacheada, criação de cache e saída

O de custo:

GET /v1/organizations/cost_report

Esse devolve custo por serviço em USD, como strings decimais, cobrindo tokens, web search e code execution

Os dois pedem a Admin API key sk-ant-admin, não a chave padrão

O erro comum deste passo: tentar autenticar com a chave de API do projeto e ficar batendo cabeça no 401

Sem código também dá: a página de Cost and Usage Reporting do Claude Console filtra por workspace, modelo, período (mês ou dia) e chave de API, e exporta em CSV

Pra quem só quer levar o número pra reunião, o CSV resolve

Como ler o resultado: três diagnósticos que a auditoria entrega

Número solto não muda nada

O que muda é o diagnóstico que ele permite. E, na prática, quase todo caso cai em um destes três

Diagnóstico 1, contexto arrastado:

Sintoma: o /context mostra a janela lotada e a flag de long context acende no /usage

Isso é histórico inchado sendo reenviado a cada turno

Ação: /compact pra resumir a conversa e liberar espaço, e delegar a saída verbosa a subagents. A própria documentação de custos aponta esse caminho: mandar rodar testes, buscar documentação ou processar logs num subagent mantém a saída barulhenta no contexto DELE e devolve só um resumo pra conversa principal

É a diferença entre despejar 800 linhas de log no seu contexto e receber "3 testes falharam, aqui está o motivo"

Diagnóstico 2, cache mal aproveitado:

Sintoma: cache_creation_input_tokens alto, cache_read_input_tokens baixo, e a flag de cache misses acesa no /usage (lembrando: ela só acende a partir de 10% do uso recente)

Leitura: tu está pagando a taxa maior pra ESCREVER cache e quase não colhe a taxa reduzida de LEITURA

Aqui o alvo do corte não é o tamanho do prompt, é o que está invalidando o cache entre uma chamada e outra

Diagnóstico 3, o culpado nomeado:

Sintoma: nada parece absurdo, mas o total não fecha com a percepção do time

Ação: abre a atribuição do /usage por skills, subagents, plugins e MCP servers

Cada peça aparece como percentual do total, então em vez de "vamos usar menos MCP", tu consegue dizer qual servidor especificamente come a fatia

Muito mais confortável de defender numa call, né? 🙂

Auditoria contínua: telemetria do Claude Code e o Agent SDK

Tudo acima é foto pontual

Se tu quer série histórica (gráfico, alerta, comparação semana a semana), o caminho é telemetria

1. Ative a exportação no Claude Code por variáveis de ambiente

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://seu-coletor:4317

O OTEL_METRICS_EXPORTER aceita otlp, prometheus, console ou none. Se tu só quer ver saindo alguma coisa na tela antes de montar coletor, console já serve

O destino vai em OTEL_EXPORTER_OTLP_PROTOCOL e OTEL_EXPORTER_OTLP_ENDPOINT

2. Leia a métrica que interessa

A métrica claude_code.token.usage separa o consumo em input, output, cache read e cache creation, e quebra por modelo

É o mesmo recorte do bloco usage da API, só que virando linha do tempo em vez de resposta única

3. Valide que a telemetria está chegando

O erro comum deste passo: configurar tudo, não ver dado nenhum e concluir que "não funciona"

A checagem indicada é procurar no seu backend a métrica emitida no início da sessão:

claude_code.session.count

Se nada chegar, roda o CLI em modo debug pra ver os erros de export do OTel:

claude --debug

Normalmente o problema aparece ali, endpoint errado ou protocolo trocado

4. Se você constrói em cima do Agent SDK, colete no fim de cada chamada

O SDK devolve custo e uso quando a chamada termina: o result message traz total_cost_usd e o usage cumulativo

O uso por passo fica em message.message.usage no TypeScript e em message.usage no Python

O custo por modelo fica em modelUsage (TS) e model_usage (Python)

for await (const message of query({ prompt })) {
  if (message.type === "result") {
    console.log(message.total_cost_usd)
    console.log(message.usage)
    console.log(message.modelUsage)
  }
}

Alerta que evita dor de cabeça: cada query() reporta apenas o custo daquela chamada, não o acumulado da sessão multi-turno

Se o teu agente faz cinco chamadas, tu soma as cinco. Já me ferrei uma vez confiando num número que era só do último passo

Meça primeiro, corte depois

A ordem é essa e não tem atalho: número antes de dica

Vale lembrar que a forma de medição muda conforme o tipo de conta. Em Team e Enterprise, o uso consome a alocação do assento de cada membro. Via Console e provedores de nuvem, o uso é cobrado por token da organização, com cada dev medido pelo método de autenticação que ele usou

E, de novo: o dólar que o CLI mostra é estimativa local calculada a partir das contagens de token. Billing autoritativo é a página Usage do Console

Próximo passo concreto pra hoje: na próxima tarefa que parecer cara, roda /usage e /context antes de mexer em qualquer coisa, e compara com o bloco usage que volta na resposta

Se os três apontarem pro mesmo lugar, tu achou o gasto

Se apontarem pra lugares diferentes, melhor ainda: tu acabou de descobrir que estava cortando a coisa errada 😀

até o próximo post!