Como a API de Administração de Uso e Custo Modela Seus Gastos

Cada solicitação que você envia para o Claude produz mais de um número que vale a pena rastrear.

Há a entrada que você escreveu, o contexto que você reutilizou do cache e a saída que o Claude gerou, e cada um desses é precificado de forma diferente.

A API de Administração de Uso e Custo é construída em torno dessa realidade: ela não entrega um único valor de "custo" por solicitação.

Em vez disso, ela fornece uma divisão estruturada, agrupada por tipo de token e organizada por dimensões como chave de API, workspace e modelo, que você pode remontar em qualquer relatório que realmente precise.

Entender esse modelo de baldes, antes de escrever uma única consulta, é o que torna o restante da API previsível em vez de confuso.

Resumo

Ideia Central: A API de Administração reporta o uso como baldes de tipo de token separados (entrada não cacheada, entrada cacheada, criação de cache, saída) em vez de um único número de custo misto.
Por que Importa: Cada balde tem um preço diferente por token, então colapsá-los cedo esconde de onde seus gastos realmente vêm.
Conceitos Chave: baldes de token, dimensões de agrupamento, uso vs. custo, nível de serviço, granularidade de tempo.
Quando Usar: Recorra a este modelo sempre que precisar explicar, auditar ou prever gastos, em vez de apenas olhar um total.
Limitações / Trade-offs: A API fornece as matérias-primas para um relatório de custos, não um relatório finalizado; você ainda precisa aplicar sua própria precificação e construir sua própria agregação.
Tópicos Relacionados: precificação consciente de cache, atribuição por chave, modelagem de chargeback, painéis do Console.

Fundamentos

Em sua essência, a API de Administração trata cada solicitação como uma pequena transação com até quatro itens.

Tokens de entrada não cacheados são os tokens de prompt que o Claude teve que processar do zero, sem um acerto de cache anterior.

Tokens de entrada cacheados são tokens de prompt servidos de um cache previamente escrito, cobrados com um desconto acentuado em comparação com tokens não cacheados.

Tokens de criação de cache são os tokens pelos quais você pagou um prêmio para escrever no cache em primeiro lugar, para que uma solicitação posterior pudesse lê-los de volta de forma barata.

Tokens de saída são o que o Claude gerou em resposta, e são precificados mais alto dos quatro, já que a geração é a parte mais intensiva em computação de uma solicitação.

Uma analogia simples: pense em um recibo de restaurante que lista o aperitivo, o prato principal e a sobremesa em vez de imprimir um total.

Você poderia pedir apenas o total, mas a versão detalhada é o que permite identificar que a sobremesa, não o prato principal, é onde a conta aumentou.

A API de Administração é construída para entregar esse recibo detalhado para cada solicitação em toda a sua organização, não apenas para uma refeição.

Cada registro de uso da API carrega essas quatro contagens de tokens, mais metadados descrevendo a qual chave de API, workspace, modelo e nível de serviço a solicitação pertence.

Esses metadados são o que transforma uma pilha de recibos em algo que uma equipe financeira, ou um engenheiro investigando um pico de custo, pode realmente consultar.

Mecânicas e Interações

O modelo mental da API tem duas metades distintas: uso e custo.

Uso é uma contagem, o número bruto de tokens de cada tipo consumido em uma determinada janela de tempo, fatiado pelas dimensões de agrupamento escolhidas.

Custo é o uso multiplicado pelo preço, expresso em dólares, e reportado na mesma granularidade do uso para que você possa rastrear um valor em dólar de volta aos tokens que o produziram.

Essa separação é importante porque os preços podem mudar ao longo do tempo, e uma consulta de uso pura permite que você repricifique dados históricos sob uma nova tabela de taxas sem ter que buscar nada novamente.

import anthropic
 
client = anthropic.Anthropic()
 
# O uso é agrupado por tipo de token e organizado pelas dimensões que você escolher
report = client.beta.usage.cost_report(
    starting_at="2026-06-01T00:00:00Z",
    group_by=["workspace_id", "model"],
)

As dimensões de agrupamento agem como uma cláusula GROUP BY em SQL: você escolhe em quais colunas fatiar, e a API retorna uma linha para cada combinação única.

Agrupe por api_key_id e você obterá gastos por chave, útil para chargeback.

Agrupe por model e você verá se uma escolha de modelo cara, e não o volume de solicitações, está impulsionando a conta.

Agrupe por service_tier e você pode separar o tráfego de nível padrão do tráfego de nível de lote ou prioritário, que têm pontos de preço diferentes.

A granularidade de tempo interage com o agrupamento também: um balde diário por workspace conta uma história muito diferente de um balde horário por chave de API, e a API permite que você escolha ambos independentemente.

Um erro de raciocínio comum é tratar "uso" e "custo" como sempre em sincronia.

Eles geralmente estão, mas nem sempre, já que uma mudança de preço, um crédito promocional ou um desconto de nível de serviço pode alterar o valor em dólares sem alterar as contagens de tokens, e a separação desses dois conceitos pela API é precisamente o que permite que você note isso.

Considerações Avançadas e Aplicações

Em escala, o modelo de balde de token se torna a base para duas coisas que toda organização de engenharia eventualmente precisa: atribuição e previsão.

Atribuição significa responder "quem gastou isso", o que requer agrupamento por chave de API ou workspace e o acúmulo para uma equipe ou produto.

Previsão significa responder "quanto custará o próximo mês", o que requer granularidade histórica suficiente para modelar tendências por tipo de token, já que a adoção de cache, a mistura de modelos e o comprimento do prompt cada um se movem independentemente.

O modelo de balde também tem um ângulo direto de segurança e governança: como os tokens de criação de cache e de leitura de cache são visíveis separadamente, você pode detectar um workspace que paga repetidamente para reescrever um cache que nunca lê de volta, o que geralmente é um sinal de uma chave de cache mal configurada em vez de uma escolha deliberada.

Abordagem	Força	Fraqueza	Melhor Ajuste
Consultar a API de Administração diretamente	Granularidade histórica completa, scriptável, agrupável por qualquer dimensão	Requer que você construa seu próprio armazenamento e visualização	Relatórios automatizados recorrentes, pipelines de chargeback
Usar as páginas de Uso e Custo do Console	Não requer código, rápido para perguntas ad hoc	Não automatizável, limitado às fatias integradas da UI	Investigações únicas, verificações rápidas
Armazenar em cache a resposta da API em seu próprio data warehouse	Permite junções com dados de produto ou cliente, análise de tendências históricas	Você é o proprietário da atualidade e correção do cache	Painéis financeiros de longa duração

À medida que as organizações amadurecem além de uma única chave de API, o modelo de balde escala naturalmente para um modelo de chargeback, onde os mesmos dados de uso e custo por chave respondem "o que gastamos" e também "qual orçamento de equipe isso atinge".

Essa é uma decisão de governança sobreposta aos mesmos dados brutos, não uma API diferente.

Conceitos Errôneos Comuns

"Custo é apenas uso vezes um único preço." Na realidade, cada tipo de token tem seu próprio preço, então a mesma solicitação pode ter quatro taxas diferentes por token em uma única conta.
"Tokens cacheados são gratuitos." Eles são fortemente descontados, não gratuitos, e os tokens de criação de cache são, na verdade, precificados com um prêmio sobre os tokens de entrada padrão.
"A API de Administração e o Console mostram números diferentes." Eles leem os mesmos registros de uso subjacentes; qualquer discrepância aparente geralmente vem de janelas de tempo ou escolhas de agrupamento diferentes, não de dados diferentes.
"Mais dimensões de agrupamento sempre significam um relatório melhor." Agrupamento excessivo fragmenta os dados em linhas muito granulares para raciocinar; escolha as duas ou três dimensões que respondem à sua pergunta real.
"Dados de uso estão disponíveis em tempo real." O uso e os dados de custo têm latência de ingestão, portanto, atividades muito recentes podem não aparecer ainda, o que é importante se você estiver construindo alertas em cima disso.

FAQs

Qual é a diferença entre uso e custo na API de Administração?

Uso é uma contagem de tokens, dividida por tipo (entrada não cacheada, entrada cacheada, criação de cache, saída).
Custo é o uso multiplicado pelo preço, expresso em dólares, na mesma granularidade do uso.
Separar os dois permite repricificar o uso histórico ou auditar uma anomalia de custo de volta às suas contagens de tokens.

Por que a API separa tokens de entrada cacheados e não cacheados em vez de relatar um total de entrada?

Porque eles são precificados de forma completamente diferente. Tokens de entrada cacheados são descontados, tokens não cacheados não são, e tokens de criação de cache têm um prêmio, então agrupá-los em um único número ocultaria a maior parte do sinal que uma investigação de custo precisa.

O que são tokens de criação de cache e por que eles custam mais do que tokens de entrada não cacheados?

Tokens de criação de cache são o que você paga quando escreve conteúdo novo no cache de prompt pela primeira vez. O prêmio reflete o trabalho extra de preparar esse conteúdo para reutilização rápida, e compensa quando solicitações posteriores o leem de volta na taxa descontada de cache.

O que significa "agrupamento" no contexto de um relatório de uso?

É análogo ao GROUP BY do SQL: você escolhe dimensões (chave de API, workspace, modelo, nível de serviço e outros) e a API retorna uma linha para cada combinação única.
Mais dimensões de agrupamento produzem linhas mais numerosas e mais finas.
Escolher o agrupamento correto é o que transforma o uso bruto em um relatório legível.

Os dados da API de Administração são os mesmos que vejo nas páginas de Uso e Custo do Console?

Sim, ambos leem os mesmos registros de uso subjacentes. Diferenças que você notar são quase sempre devido a janelas de tempo, fusos horários ou escolhas de agrupamento diferentes, em vez de dados subjacentes diferentes.

Uma contagem maior de tokens sempre significa um custo maior?

Não necessariamente. Uma grande solicitação de entrada não cacheada e uma pequena solicitação com muita saída podem custar quantias semelhantes, já que os tokens de saída são os mais caros dos quatro baldes. A contagem de tokens e o custo em dólares só se movem em sincronia quando a mistura de tokens permanece constante.

O que é nível de serviço e por que ele aparece nos dados de uso?

O nível de serviço reflete como uma solicitação foi roteada, por exemplo, processamento padrão versus em lote ou prioritário, e cada nível pode ter um preço diferente. Agrupar por nível de serviço permite que você veja quanto de seus gastos vem de cada escolha de roteamento.

Posso usar a API de Administração para ver custos de antes de eu começar a monitorá-los ativamente?

Sim, dentro da janela de retenção de dados da plataforma. Essa é uma das principais vantagens de uma API histórica e agrupada em vez de um painel apenas em tempo real: você pode reconstruir os gastos de um período que você não estava observando de perto.

Por que eu consultaria o uso sem também pedir o custo?

Consultas apenas de uso são úteis quando você deseja reaplicar seu próprio modelo de precificação, por exemplo, simulando "quanto teria custado este mês sob uma taxa diferente", ou quando você está diagnosticando um problema de volume de tokens que é independente do preço.

Qual é o erro de raciocínio mais comum que as pessoas cometem com esses dados?

Assumir que uso e custo sempre andam juntos. Mudanças de preço, descontos ou uma mudança na mistura de tokens (mais leituras cacheadas, menos não cacheadas) podem alterar o custo sem uma mudança proporcional nas contagens brutas de tokens, e vice-versa.

Preciso construir meu próprio painel para usar esses dados?

Não necessariamente para perguntas ad hoc, as páginas de Uso e Custo do Console cobrem essas. Mas para relatórios recorrentes, chargeback ou previsão, a maioria das equipes acaba construindo um pequeno pipeline sobre a API de Administração para que os dados cheguem a um local consultável junto com outras métricas de negócios.

Como este modelo de balde se relaciona com um modelo de chargeback entre equipes?

Um modelo de chargeback é uma camada de governança construída sobre os mesmos dados: ele pega o uso e o custo por chave de API ou por workspace e aplica uma política de como isso será cobrado das equipes internas. Os baldes de token subjacentes não mudam, apenas como você os atribui e divide.

Relacionados

Noções Básicas de Rastreamento de Uso e Custo - obtenha seu primeiro relatório de uso e veja o modelo de balde em uma resposta real.
Consultando Uso por Chave de API e Workspace com a API de Administração - aplique dimensões de agrupamento para isolar uma única chave ou workspace.
Construindo um Painel de Custos a partir de Divisões de Tokens Não Cacheados, Cacheados e de Saída - transforme esses baldes em um painel que uma equipe financeira possa ler.
Comparação: API de Administração vs. Páginas de Uso e Custo do Console - decida quando o painel é suficiente e quando você precisa da API.
Modelo ADR: Um Modelo de Chargeback para Uso de Chave de API Multi-Equipe - veja como este modelo de balde se torna uma política de faturamento de equipe.

Versões de Stack: Escrito com base na linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.