O que são tokens no Claude e como funcionam? Contamos 3,8 bilhões

Você encontra a palavra em todo lugar em volta do Claude: na tabela de preços, na mensagem de limite, no /usage, em cada artigo sobre como economizar. Quase ninguém diz o que é um token, e o número que as pessoas olham raramente é o que importa. O que o Claude escreve de volta é uma fração de um por cento do que uma sessão de programação contabiliza.

Então contamos os nossos. Trinta dias de sessões do Claude Code em um Mac, de 10 de setembro a 9 de outubro de 2026: 388 sessões, 19.668 requisições ao modelo, 3,8 bilhões de tokens. Isto é o que é um token, as quatro formas como o Claude os conta e como esses números ficam em trabalho real.

Um token é um pedaço de texto, e o tamanho do pedaço muda

Um modelo não lê letras nem palavras. Ele lê tokens: pedaços de texto tirados de um vocabulário fixo, às vezes uma palavra curta inteira, muitas vezes parte de uma palavra, às vezes um único caractere ou byte para algo que ele nunca viu. Tudo é contado nesses pedaços: o que você envia, o que o Claude escreve, o que ele guarda de um turno para o outro.

Quanto texto cabe em um token depende do modelo e do idioma. O glossário da Anthropic indica cerca de 3,5 caracteres em inglês por token nos modelos anteriores ao Claude 4.7, e diz que o Claude 4.7 e os seguintes usam um tokenizador mais novo que produz cerca de 30% mais tokens para o mesmo texto. A contagem exata só sai do endpoint de contagem de tokens, com o modelo que você pretende usar.

Medimos a proporção no nosso próprio texto. Nossos agentes respondem em francês, então pegamos as respostas que eram só texto, sem raciocínio, sem chamada de ferramenta, sem bloco de código, com pelo menos 80 palavras: 296 respostas distribuídas entre Opus 5, Opus 5.5, Fable 5.1 e Sonnet 5.5. A mediana foi de 2,3 caracteres por token, cerca de 2,6 tokens por palavra. Código, JSON e escritas não latinas dão outras proporções. O que importa não é o número exato: um token é menor que uma palavra, e você nunca os conta à mão.

Cada requisição é contada em quatro contadores

O Claude Code grava cada sessão em uma transcrição JSONL em ~/.claude/projects/. Cada resposta do modelo traz um bloco usage. Aqui está um real, tirado das nossas transcrições, com os campos úteis:

"usage": {
  "input_tokens": 2,
  "cache_creation_input_tokens": 51836,
  "cache_read_input_tokens": 24882,
  "output_tokens": 315,
  "output_tokens_details": { "thinking_tokens": 54 },
  "cache_creation": {
    "ephemeral_1h_input_tokens": 51836,
    "ephemeral_5m_input_tokens": 0
  }
}

Quatro contadores, e eles não custam o mesmo:

• input_tokens: a parte do prompt que não é gravada no cache nem lida dele, cobrada pelo preço base de entrada. No Claude Code, quase sempre é um punhado de tokens, porque quase tudo passa pelo cache.
• cache_creation_input_tokens: a parte do prompt armazenada no cache para que a próxima requisição possa reutilizá-la. Uma gravação de cache custa 1,25 vez o preço de entrada para um cache de 5 minutos e 2 vezes para um cache de 1 hora. Nas nossas transcrições, 97% das gravações eram do cache de 1 hora.
• cache_read_input_tokens: a parte do prompt reaproveitada do cache. Uma leitura de cache custa 0,1 vez o preço de entrada na maioria dos modelos, 0,05 vez no Opus 5.5 e no Sonnet 5.5, e 0,025 vez no Fable 5.1 (página de prompt caching da Anthropic, consultada em 10 de outubro de 2026).
• output_tokens: o que o Claude escreve, raciocínio incluído. A saída custa 5 vezes o preço de entrada em todos os modelos atuais: 20 dólares por milhão no Opus 5.5, 25 no Opus 5, 50 no Fable 5.1, 10 no Sonnet 5.5.

Os três primeiros somados formam o contexto que o modelo leu para essa requisição. O quarto é a resposta.

Como ficam 30 dias das nossas sessões

Nas 19.668 requisições, contadas uma vez por requisição (uma mesma chamada de API pode ocupar várias linhas de uma transcrição):

A coluna de custo precifica cada requisição com o próprio modelo e a própria duração de cache. Não pagamos esse valor: essas sessões rodavam em uma assinatura. É o peso de cada contador, a mesma ponderação que o AgentsRoom usa para dividir a porcentagem de um plano entre projetos.

Três leituras.

Quase todo token é a conversa sendo relida. 97,7% dos tokens são leituras de cache. 99,2% das requisições leem algo do cache. Quando alguém diz que uma sessão "consumiu 50 milhões de tokens", é isso que está olhando.

O que o Claude escreve é pouco em tokens e não é pouco em custo. 0,34% dos tokens, 16,8% da conta, porque a saída é o token mais caro que existe. O raciocínio foi 29% dessa saída.

As gravações de cache são a surpresa cara. 2% dos tokens, 37% do custo. Esperávamos que viessem da expiração do cache, mas só 16 requisições de 19.668 precisaram regravar um contexto frio, sete delas depois de mais de uma hora de silêncio. 79% das gravações são simplesmente cada nova mensagem e cada resultado de ferramenta armazenado uma vez, pelo dobro do preço de entrada, antes de ser relido em cada turno seguinte. Os outros 20% são a primeira requisição de cada sessão.

Por que uma sessão fica mais pesada a cada turno

O modelo não guarda nada entre duas requisições. O Claude Code envia tudo de novo a cada vez: o prompt de sistema, as definições de ferramentas, o CLAUDE.md, cada mensagem, cada arquivo que leu, cada saída de comando. O cache deixa a parte repetida barata por token, não gratuita, e não menor.

Contexto mediano lido por requisição, conforme a posição na sessão:

A requisição mediana leu 179.000 tokens de contexto para escrever 290 tokens de resposta. Essa proporção resume toda a história dos tokens em um agente de programação: a resposta é curta, a leitura é longa, e a leitura cresce com a sessão.

Nossa primeira requisição é pesada, 52.000 tokens antes de alguém digitar qualquer coisa, porque nossos agentes começam com um briefing de papel longo e quatro servidores MCP cujas definições de ferramentas ficam no prompt. Uma sessão do Claude Code sem nada, em uma pasta vazia, começa bem mais abaixo. O /context mostra o que a sua carrega antes da primeira mensagem.

O que uma sessão consome

Nas 380 sessões com pelo menos três requisições:

• 33 requisições na mediana, de 16 a 61 para a metade central.
• 27.000 tokens de saída na mediana, de 12.000 a 48.000.
• 5,4 milhões de tokens processados na mediana, de 1,5 a 10,7 milhões para a metade central, dos quais 5,1 milhões eram leituras de cache.
• 181.000 tokens gravados no cache ou enviados sem cache na mediana: a parte que era realmente nova.
• 4,55 dólares pelos preços de tabela da API na mediana, de 1,81 a 9,25 para a metade central.

Então a resposta honesta para "quantos tokens uma sessão de programação consome" é uma faixa de cerca de um a dez milhões, quase tudo o mesmo contexto lido de novo. Uma sessão que roda a tarde inteira em uma única tarefa longa fica no topo da faixa; uma sessão que corrige um bug e para fica na base.

O que a janela de 5 horas e a semana realmente contam

Em um plano Pro ou Max, você nunca vê um saldo de tokens. A central de ajuda da Anthropic diz que os dois planos têm um limite de sessão de cinco horas e um limite semanal, que esses limites são compartilhados entre o Claude e o Claude Code (IDE incluída), e que os planos Max têm um limite semanal separado para o Fable. Ela não publica nenhum número em tokens para nenhum deles. O /usage mostra uma porcentagem de cada janela e o horário em que ela é zerada.

O que move essa porcentagem, na própria lista da Anthropic: o tamanho da mensagem, o tamanho dos anexos, o tamanho da conversa atual, o uso de ferramentas, a escolha do modelo, o nível de esforço e as tarefas de várias etapas. Lido junto com as tabelas acima, "o tamanho da conversa atual" é o que domina uma sessão de programação: o contexto lido a cada requisição passa de 52.000 para 237.000 tokens em cinquenta requisições. A central de ajuda também diz que o conteúdo em cache nos projetos conta menos nos seus limites quando é reutilizado, que é a mesma ideia do preço de uma leitura de cache.

Não sabemos como a Anthropic converte tokens em porcentagem de uma janela, e não vamos inventar uma conversão. O que os dados dizem é que uma requisição tardia em uma sessão longa conta várias vezes o que conta uma do começo, para a mesma pergunta.

O que muda a contagem, na prática

Quatro alavancas, na ordem em que pesam nos nossos dados:

• /clear entre tarefas sem relação. A Anthropic o chama de "a alavanca mais eficaz, tanto para a qualidade quanto para o custo". Uma tarefa nova em uma sessão antiga paga o contexto da tarefa anterior em cada requisição.
• /compact quando você continua uma sessão longa. Ele substitui o histórico por um resumo curto, então as próximas requisições leem menos.
• Preste atenção no que entra no contexto. Uma leitura de arquivo ou uma saída de comando de 20.000 tokens é gravada uma vez pelo dobro do preço de entrada e depois relida em cada requisição seguinte até o fim da sessão. Ler só as linhas de que você precisa, em vez do arquivo inteiro, compensa duas vezes.
• Modelo e esforço. O raciocínio foi 29% da nossa saída, e a saída é o token mais caro. Um nível de esforço mais baixo no trabalho de rotina reduz a saída, e um modelo mais barato reduz todos os preços de uma vez.

O que não pesou nos nossos dados: deixar uma sessão ociosa. Com o cache de 1 hora que o Claude Code usa nas nossas transcrições, uma regravação a frio aconteceu 16 vezes em 30 dias.

Para mais formas de gastar menos, veja como reduzir seus custos de tokens no Claude Code.

Conte os seus

A tabela acima vem de um script sem dependências. Ele lê todas as transcrições do Claude Code da máquina, conta cada requisição uma vez e mostra os quatro contadores e as medianas por sessão. Adicione um filtro em o["timestamp"] se quiser uma janela de tempo.

import json, glob, os, statistics as st
from collections import defaultdict

FIELDS = ("input_tokens", "cache_creation_input_tokens",
          "cache_read_input_tokens", "output_tokens")
totals, sessions = defaultdict(int), []
for path in glob.glob(os.path.expanduser("~/.claude/projects/*/*.jsonl")):
    seen, session = set(), defaultdict(int)
    with open(path, errors="ignore") as fh:
        for line in fh:
            try: o = json.loads(line)
            except ValueError: continue
            msg = o.get("message") or {}
            usage = msg.get("usage") if isinstance(msg, dict) else None
            if o.get("type") != "assistant" or not usage: continue
            rid = o.get("requestId") or o.get("uuid")
            if rid in seen: continue   # one API call can span several lines
            seen.add(rid)
            session["requests"] += 1
            for f in FIELDS:
                n = usage.get(f) or 0
                totals[f] += n
                session[f] += n
    if session["requests"] >= 3: sessions.append(session)

grand = sum(totals[f] for f in FIELDS)
for f in FIELDS:
    print(f"{f:30s} {totals[f]:>15,} {100 * totals[f] / grand:6.2f}%")
for key in ("requests", "output_tokens", "cache_read_input_tokens"):
    print(f"median per session, {key}: {st.median(s[key] for s in sessions):,.0f}")

Compare as suas parcelas com as nossas. A linha das leituras de cache é a conversa sendo relida, e a linha das gravações de cache é o que era novo: essas duas dizem mais sobre a sua conta do que a linha de saída.

Onde o AgentsRoom mostra isso

O script te dá um mês. Enquanto você trabalha, o AgentsRoom mostra os mesmos contadores por agente: um selo de tokens no compositor de cada sessão que fica vermelho quando uma sessão fica pesada, um monitor de sessão com entrada, saída, gravações de cache, leituras de cache e a taxa de acerto do cache, e um rastro de sessão que reproduz a sessão turno a turno para mostrar qual leitura de arquivo ou qual resultado de ferramenta encheu o contexto. O painel de uso divide a porcentagem que o seu plano informa entre seus projetos e seus agentes, ponderando cada sessão pelo que ela custaria pelos preços da API, a mesma ponderação da tabela acima.

O que nada disso te dá é um saldo de tokens, porque o seu plano não tem um. Para essa pergunta, veja quantos tokens ainda restam no Claude. Para a velocidade com que esses tokens de saída chegam, veja os tokens por segundo do Claude Code, medidos.

Perguntas frequentes

O que é um token no Claude?

A unidade em que o Claude lê e escreve texto: um pedaço de palavra, às vezes uma palavra curta inteira, às vezes um único caractere ou byte. A Anthropic diz que o tamanho depende do modelo e do idioma: nos modelos anteriores ao Claude 4.7, um token tinha cerca de 3,5 caracteres em inglês, e o Claude 4.7 e os seguintes usam um tokenizador mais novo que produz cerca de 30% mais tokens para o mesmo texto. Tudo o que o Claude faz é medido em tokens: o que você envia, o que ele responde e o que ele guarda no cache de um turno para o outro.

Quantos caracteres ou palavras tem um token do Claude?

Depende do idioma e do texto. A Anthropic indica cerca de 3,5 caracteres em inglês por token nos modelos anteriores ao Claude 4.7, e cerca de 30% mais tokens para o mesmo texto no Claude 4.7 e nos seguintes. Em 296 respostas só de texto que nossos agentes escreveram em francês em setembro e outubro de 2026, um token tinha 2,3 caracteres, ou cerca de 2,6 tokens por palavra. Código, JSON e escritas não latinas dão outras proporções. Para uma contagem exata, o endpoint de contagem de tokens da Anthropic recebe o texto e o modelo.

Por que o Claude Code consome tantos tokens?

Porque cada requisição envia de novo a conversa inteira: o prompt de sistema, as definições de ferramentas, o CLAUDE.md, cada mensagem e cada resultado de ferramenta até ali. Nas nossas 19.668 requisições, a requisição mediana carregava 179.000 tokens de contexto para escrever 290 tokens de resposta, e o contexto passava de 52.000 tokens na primeira requisição de uma sessão para 237.000 depois de cinquenta requisições. O cache deixa essa releitura barata por token, mas ela continua sendo contada.

Quantos tokens uma sessão típica do Claude Code consome?

Nas nossas 380 sessões de três requisições ou mais, registradas entre 10 de setembro e 9 de outubro de 2026: uma mediana de 33 requisições, 27.000 tokens de saída e 5,4 milhões de tokens processados no total, dos quais 5,1 milhões eram leituras de cache. Metade das sessões ficou entre 1,5 e 10,7 milhões de tokens. Pelos preços de tabela da API, essa sessão mediana teria custado cerca de 4,55 dólares; em um plano Pro ou Max, o mesmo trabalho é descontado das janelas de 5 horas e semanal.

Os tokens de raciocínio contam?

Sim. Os tokens de raciocínio fazem parte de output_tokens em cada bloco usage, com um campo thinking_tokens que diz quanto da saída foi raciocínio. Eles são cobrados pelo preço de saída na API, e a Anthropic inclui o nível de esforço entre o que faz os limites de uso de um plano acabarem mais rápido. No nosso corpus, o raciocínio foi 29% de tudo o que os modelos escreveram.

Qual é a diferença entre tokens de gravação de cache e de leitura de cache?

Uma gravação de cache armazena parte do prompt para que a próxima requisição possa reutilizá-la, e custa mais que a entrada simples: 1,25 vez o preço de entrada para um cache de 5 minutos, 2 vezes para um cache de 1 hora. Uma leitura de cache reutiliza essa parte armazenada e custa muito menos: 0,1 vez o preço de entrada na maioria dos modelos, 0,05 vez no Opus 5.5 e no Sonnet 5.5, 0,025 vez no Fable 5.1. Nas nossas sessões, as leituras de cache foram 98% dos tokens e 46% do custo pelos preços de tabela; as gravações de cache, 2% dos tokens e 37% do custo.