O caso: uma software house atende três clientes com a API do Claude, cada um num espaço de trabalho (workspace) próprio. No fim do mês, precisa dizer quanto cada cliente gastou, por modelo e por chave. O que muda com a API lançada em 29/10/2026?
Resposta curta: a nova Usage and Cost Analytics API (beta) devolve o custo em dólar já separado por workspace, chave, modelo e quem fez o pedido. No exemplo deste texto, a fatura de US$ 4.680,00 (cerca de R$ 23.444,93) se divide em três linhas, uma por cliente, numa única consulta. O cuidado é o prazo: os dados chegam em até 24 horas, não em minutos.
O que foi lançado
Em 29 de outubro de 2026, a Anthropic publicou nas notas de versão da plataforma a Usage and Cost Analytics API, em beta. São dois endpoints:
| Endpoint | O que devolve | Ordena por |
|---|---|---|
GET /v1/organizations/analytics/usage |
Tokens por tipo e número de pedidos | total_tokens (padrão), output_tokens, uncached_input_tokens, requests ou time |
GET /v1/organizations/analytics/cost |
Custo em dólar, com e sem descontos | amount (padrão), list_amount ou time |
Cada pedido precisa do cabeçalho anthropic-beta: analytics-usage-cost-2026-08-24. Em organizações da Claude Console, a chamada usa uma chave de administrador (Admin API). No Claude Enterprise, usa uma chave com o escopo read:analytics. A API também funciona no Claude Platform on AWS e no Claude no Google Cloud gerido pela Anthropic, cada um com a sua autenticação.
No mesmo dia, a antiga Usage and Cost API e os relatórios de uso e custo do Enterprise Analytics passaram a ser legado. Continuam funcionando, segundo a nota.
Passo 1: entenda o formato do custo
O campo amount vem em centavos de dólar, como texto com seis casas decimais. A documentação dá o exemplo: "41280.000000" é US$ 412,80. Quem somar o campo direto e tratar como dólar vai inflar a conta em 100 vezes.
Cada linha do custo traz dois valores:
amount: o custo depois dos descontos e antes dos créditos;list_amount: o custo pelo preço de tabela.
A moeda é sempre "USD". A conversão para reais fica com você. Neste texto usamos o dólar de referência do site, de R$ 5,01.
Passo 2: confira uma linha com o preço de tabela
A documentação mostra uma linha de exemplo do endpoint de uso, com um dia de tokens de um modelo. Para ver como os tipos de token pesam, aplicamos a esses números os preços do Sonnet 5.5 do arquivo do site. É só um exercício: a linha da documentação é de outro modelo.
| Tipo de token (campo da API) | Tokens | Preço por milhão | Custo |
|---|---|---|---|
Entrada sem cache (uncached_input_tokens) |
1.284.500 | US$ 2,00 | US$ 2,57 |
Gravação no cache de 5 min (ephemeral_5m_input_tokens) |
215.300 | US$ 2,50 | US$ 0,54 |
Leitura do cache (cache_read_input_tokens) |
3.200.000 | US$ 0,10 | US$ 0,32 |
Saída (output_tokens) |
891.000 | US$ 10,00 | US$ 8,91 |
| Total do dia | 5.590.800 | US$ 12,34 |
Se esse dia fosse de Sonnet 5.5, o endpoint de custo devolveria em list_amount algo perto de 1.233,73 centavos. Note o peso de cada linha: a leitura do cache tem a maior quantidade de tokens e um dos menores custos. A saída, com menos de um milhão de tokens, responde por 72% do total.
Para conferir a quebra no seu caso, o endpoint de custo aceita group_by[]=token_type, que separa o custo de tokens por tipo, e group_by[]=cost_type, que separa tokens, busca na web, execução de código e uso de sessão.
Passo 3: a conta por cliente
Voltemos à software house. Os volumes abaixo são exemplo, para um mês:
- Cliente A, chatbot no Sonnet 5.5: 900.000.000 tokens de entrada sem cache, 1.500.000.000 lidos do cache e 60.000.000 de saída.
- Cliente B, classificação no Haiku 5.5: 2.000.000.000 de entrada e 100.000.000 de saída, em pedidos curtos.
- Cliente C, agente no Opus 5.5: 300.000.000 de entrada, 900.000.000 lidos do cache e 25.000.000 de saída.
| Cliente (workspace) | Modelo | Custo no mês | Em reais | Parte da fatura |
|---|---|---|---|---|
| A | Sonnet 5.5 | US$ 2.550,00 | R$ 12.774,48 | 54,5% |
| B | Haiku 5.5 | US$ 250,00 | R$ 1.252,40 | 5,3% |
| C | Opus 5.5 | US$ 1.880,00 | R$ 9.418,05 | 40,2% |
| Total | US$ 4.680,00 | R$ 23.444,93 | 100% |
Com a API nova, essa tabela sai de uma consulta ao endpoint de custo com group_by[]=workspace_id e group_by[]=model, para o mês fechado. A consulta aceita até cinco dimensões de agrupamento. cost_type e token_type não contam nesse limite.
As dimensões disponíveis incluem modelo, workspace, chave de API, nível de serviço (service_tier), região de inferência (inference_geo), velocidade (speed), perfil de usuário (user_profile_id) e quem fez o pedido (actor). Um usuário, uma conta de serviço ou a própria chave aparecem como actor.
Se a sua empresa já usa perfis de usuário para identificar o cliente final, o agrupamento por user_profile_id dá o custo por cliente mesmo quando todos dividem o mesmo workspace.
Passo 4: o atraso dos dados
Aqui está a diferença que mais pesa na prática. A API antiga mostrava os dados, em geral, em até 5 minutos. A nova atualiza em geral em até 4 horas e pode levar até 24 horas. Cada resposta traz data_refreshed_at: o uso depois desse horário falta ou está incompleto.
Para alerta de gasto, isso conta. No exemplo, o Cliente C gasta em média US$ 62,67 por dia (R$ 313,93). Com até 24 horas de atraso, um alerta que dependa só dessa API pode enxergar o problema com até um dia inteiro de gasto já feito. Se um agente entrar em laço e gastar o dobro, a diferença invisível chega a US$ 125,33 antes de aparecer.
Os valores também podem ser revistos até cerca de 7 dias depois do fim do mês. A documentação dá o exemplo: os números de 1º de outubro podem mudar até mais ou menos 7 de novembro. Para fechar a cobrança dos clientes, consulte só meses encerrados há pelo menos 7 dias.
Limites de consulta
| Regra | Valor na documentação |
|---|---|
| Data mais antiga | 1º de janeiro de 2026, e dentro dos últimos 365 dias |
| Período máximo por pedido | 31 dias |
Faixas de tempo (time_bucket_width) |
1m, 1h ou 1d; com 1m, no máximo 24 horas por pedido |
Linhas por página (limit) |
1 a 1.000, padrão 20 |
| Valores por filtro | até 100 |
Um ano inteiro pede pelo menos 12 consultas de um mês. Os SDKs e a CLI ant buscam as páginas seguintes sozinhos.
Erros comuns na migração
- Somar
amountcomo dólar. É centavo. Divida por 100. - Esperar linhas vazias. A API antiga devolvia faixas de tempo sem uso. A nova não devolve linha quando não há uso. Preencha os dias sem dado com zero.
- Confiar no erro para ID errado. Na API nova, um ID de chave ou workspace desconhecido, ou um nome de modelo com erro de digitação, não dá erro: só não encontra nada. Um relatório com zero pode ser um filtro errado.
- Esquecer o workspace padrão. Ele agora aparece com o seu próprio
wrkspc_, e não mais comonull. - Achar que o Priority Tier sumiu. Pedidos cobertos por compromisso de Priority Tier aparecem no uso, mas com custo de tokens zero; a taxa do compromisso é cobrada à parte e não está nesses dados.
Perguntas frequentes
Preciso migrar agora?
Não. A API antiga virou legado em 29/10/2026, mas continua com suporte, segundo a nota de versão. A nova traz agrupamento por quem fez o pedido e por perfil de usuário, o que vale a troca para quem divide a fatura por cliente.
Quanto vale um amount de "500000.000000"?
São 500 mil centavos, ou US$ 5.000,00. Pelo dólar de referência do site, R$ 25.048,00.
Dá para usar a API para cortar o gasto em tempo real?
Não é o melhor uso. Com até 24 horas de atraso, no exemplo o Cliente C pode gastar US$ 62,67 antes de o dado aparecer. Para limitar o gasto na hora, conte os tokens que voltam em cada resposta da Messages API.
O custo de busca na web aparece?
Sim. O endpoint de custo tem uma linha web_search por modelo quando você agrupa por cost_type, além de code_execution e session_usage.
Como saber o custo do Claude Code por pessoa?
A documentação indica o endpoint de custo com products[]=claude_code&group_by[]=actor. Para estimar antes de ter a fatura, use a calculadora de Claude Code, Codex ou API.
Antes de abrir a consulta, faça a estimativa do mês por cliente na calculadora de custo de API de IA.
Leia também: OpenTelemetry no Claude: o custo certo de cada pedido
