Noções Básicas de Rastreamento de Uso e Custo

9 exemplos para você começar com Rastreamento de Uso e Custo - 6 básicos e 3 intermediários.

Pré-requisitos

• Instale o SDK: pip install anthropic.
• Gere uma chave de API de administrador no Console Claude (uma chave de API regular não pode chamar endpoints da API de Administrador).
• Defina ANTHROPIC_ADMIN_KEY como uma variável de ambiente em vez de codificá-la em seu script.

Exemplos Básicos

1. Obter um Relatório de Uso

Obtenha o uso bruto de tokens dos últimos 7 dias sem agrupamento.

import anthropic
from datetime import datetime, timedelta, timezone
 
client = anthropic.Anthropic(api_key=None)  # pega ANTHROPIC_ADMIN_KEY
 
start = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()
 
report = client.beta.usage.report(starting_at=start)
 
for bucket in report.data:
    print(bucket.uncached_input_tokens, bucket.output_tokens)

• report() retorna registros de uso agrupados por tempo, não um total único.
• Cada registro separa uncached_input_tokens, cached_input_tokens, cache_creation_input_tokens e output_tokens.
• Sem group_by, os resultados são agregados em toda a sua organização.

2. Obter um Relatório de Custo

Obtenha a visualização em dólares da mesma janela.

import anthropic
 
client = anthropic.Anthropic()
 
cost = client.beta.cost.report(starting_at="2026-06-01T00:00:00Z")
 
for bucket in cost.data:
    print(bucket.amount, bucket.currency)

• O endpoint de custo espelha a forma do endpoint de uso, mas retorna valores em dólares em vez de contagens de tokens.
• O custo é derivado do uso com base nos preços atuais da plataforma, não de uma entrada manual separada.
• Use o endpoint de custo quando você precisar apenas de um total em dólares; use o uso quando precisar explicar o porquê.

3. Filtrar por um Único Espaço de Trabalho

Restrinja um relatório a um ID de espaço de trabalho.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    workspace_ids=["wksp_01abc123"],
)

• workspace_ids aceita uma lista, então você pode filtrar para um ou vários espaços de trabalho em uma única chamada.
• Encontre IDs de espaço de trabalho no Console em Configurações da Organização, ou listando espaços de trabalho com a API de Administrador.
• Omitir este filtro retorna o uso de todos os espaços de trabalho aos quais você tem acesso.

4. Agrupar Uso por Espaço de Trabalho

Veja o uso de cada espaço de trabalho lado a lado, em vez de filtrar para um.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    group_by=["workspace_id"],
)
 
for bucket in report.data:
    print(bucket.workspace_id, bucket.output_tokens)

• group_by retorna uma linha por valor exclusivo da chave de agrupamento, semelhante ao GROUP BY do SQL.
• Agrupar por workspace_id é a maneira mais rápida de ver qual equipe está impulsionando o uso.
• Você pode combinar várias chaves de agrupamento em uma lista, por exemplo ["workspace_id", "model"].

5. Definir um Intervalo de Tempo com uma Data de Fim

Limite um relatório a uma janela específica em vez de "tudo desde uma data de início".

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    ending_at="2026-06-30T23:59:59Z",
)

• ending_at é opcional; omiti-lo o define como "agora".
• Ambos os carimbos de data/hora são ISO 8601 e interpretados em UTC.
• Uma janela limitada é o que você deseja para um relatório mensal que não deve mudar à medida que novos dias passam.

6. Escolher uma Granularidade de Intervalo de Tempo

Controle se os resultados retornam por dia, por hora ou como um total somado.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    ending_at="2026-06-08T00:00:00Z",
    bucket_width="1d",
)
 
for bucket in report.data:
    print(bucket.starting_at, bucket.output_tokens)

• bucket_width controla como o uso é fatiado no tempo dentro da sua janela, por exemplo "1h" ou "1d".
• Uma largura de intervalo mais fina fornece uma linha de tendência; uma largura grosseira fornece uma única figura de resumo.
• Escolha a largura para corresponder a como você planeja traçar os dados, não apenas a opção mais ampla disponível.

Relacionado: Como a API de Administrador de Uso e Custo Modela Seus Gastos - o modelo de bucket de tokens por trás desses campos

Exemplos Intermediários

7. Combinar Filtro de Espaço de Trabalho com Agrupamento por Modelo

Responda "quais modelos este espaço de trabalho está usando e quanto eles custam" em uma única chamada.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    workspace_ids=["wksp_01abc123"],
    group_by=["model"],
)
 
for bucket in report.data:
    total_input = bucket.uncached_input_tokens + bucket.cached_input_tokens
    print(bucket.model, total_input, bucket.output_tokens)

• Filtros (workspace_ids) e agrupamento (group_by) compõem livremente na mesma solicitação.
• Somar uncached_input_tokens e cached_input_tokens fornece o volume total de entrada, enquanto mantê-los visíveis separadamente preserva a história do custo.
• Este padrão é o ponto de partida para um relatório de custo por espaço de trabalho e por modelo.

8. Paginar um Relatório Grande

Percorra todas as páginas de um relatório que abrange mais dados do que cabem em uma resposta.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-01-01T00:00:00Z",
    group_by=["api_key_id", "model"],
)
 
all_buckets = list(report.data)
while report.has_next_page():
    report = report.get_next_page()
    all_buckets.extend(report.data)
 
print(len(all_buckets), "baldes de uso buscados")

• Intervalos de datas amplos combinados com chaves de group_by granulares podem produzir muitas linhas, portanto, a paginação é comum na prática.
• O objeto de página do SDK expõe has_next_page() e get_next_page() para que você não precise criar sua própria lógica de cursor.
• Sempre acumule em sua própria lista ou banco de dados; os objetos de página do SDK não se destinam a serem mantidos indefinidamente.

9. Agregar Custo por Tipo de Token

Calcule um total de custo por tipo de token a partir de um único relatório, o primeiro passo para um painel real.

import anthropic
from collections import defaultdict
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    group_by=["model"],
)
 
totals = defaultdict(int)
for bucket in report.data:
    totals["uncached_input"] += bucket.uncached_input_tokens
    totals["cached_input"] += bucket.cached_input_tokens
    totals["cache_creation"] += bucket.cache_creation_input_tokens
    totals["output"] += bucket.output_tokens
 
for token_type, count in totals.items():
    print(token_type, count)

• defaultdict(int) evita KeyErrors ao acumular contagens em muitos buckets.
• Esta é a forma bruta que um painel voltado para finanças precisa antes de aplicar preços por tipo de token.
• Manter os quatro tipos de token separados aqui, em vez de somá-los em um único número, é o que preserva a capacidade de explicar o total posteriormente.

Relacionado: Construindo um Painel de Custo a Partir de Detalhes de Tokens Não Cacheados, Cacheados e de Saída - o painel completo para o qual este padrão leva | Consultando Uso por Chave de API e Espaço de Trabalho com a API de Administrador - consultas mais restritas, de chave única e de espaço de trabalho único

Versões da Stack: Escrito contra a linha de modelos Claude atual a partir de ~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.