API de Uso e Custo

A Usage & Cost Admin API fornece acesso programático e granular aos dados históricos de uso e custo da API para sua organização. Esses dados são semelhantes às informações disponíveis nas páginas Usage e Cost do Claude Console.

Esta API permite que você monitore, analise e otimize melhor suas implementações do Claude:

• Rastreamento preciso de uso: Obtenha contagens precisas de tokens e padrões de uso em vez de depender apenas da contagem de tokens de resposta
• Reconciliação de custos: Compare registros internos com o faturamento da Anthropic para equipes de finanças e contabilidade
• Desempenho e melhoria do produto: Monitore o desempenho do produto enquanto mede se as mudanças no sistema o melhoraram, ou configure alertas
• Otimização de limite de taxa e Priority Tier: Otimize recursos como cache de prompt ou prompts específicos para aproveitar ao máximo sua capacidade alocada, ou adquira capacidade dedicada.
• Análise avançada: Realize análises de dados mais profundas do que as disponíveis no Console

Soluções de parceiros

Plataformas líderes de observabilidade oferecem integrações prontas para uso para monitorar o uso e custo da sua API do Claude, sem escrever código personalizado. Essas integrações fornecem dashboards, alertas e análises para ajudar você a gerenciar o uso da API de forma eficaz.

Início rápido

Obtenha o uso diário da sua organização nos últimos 7 dias:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-15T00:00:00Z&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

User-Agent: YourApp/1.0.0 (https://yourapp.com)

Usage API

Rastreie o consumo de tokens em toda a sua organização com detalhamentos por modelo, workspace e nível de serviço com o endpoint /v1/organizations/usage_report/messages.

Conceitos principais

• Intervalos de tempo: Agregue dados de uso em intervalos fixos (1m, 1h ou 1d)
• Rastreamento de tokens: Meça tokens de entrada sem cache, entrada com cache, criação de cache e saída
• Filtragem e agrupamento: Filtre por chave de API, workspace, modelo, nível de serviço, janela de contexto, residência de dados ou velocidade (beta), e agrupe resultados por essas dimensões
• Uso de ferramentas de servidor: Rastreie o uso de ferramentas do lado do servidor, como busca na web

Para detalhes completos de parâmetros e esquemas de resposta, consulte a referência da Usage API.

Exemplos básicos

Uso diário por modelo

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Uso por hora com filtragem

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-15T00:00:00Z&\
ending_at=2025-01-15T23:59:59Z&\
models[]=claude-opus-4-8&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Filtrar uso por chaves de API e workspaces

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\
api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Residência de dados

Rastreie seus controles de residência de dados agrupando e filtrando o uso com a dimensão inference_geo. Isso é útil para verificar o roteamento geográfico em toda a sua organização.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=inference_geo&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Você também pode filtrar por uma região geográfica específica. Os valores válidos são global, us e not_available:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
inference_geos[]=us&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Modo rápido (prévia de pesquisa)

Rastreie o uso do modo rápido agrupando e filtrando com a dimensão speed. Isso é útil para monitorar o uso do modo padrão vs. modo rápido.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Você também pode filtrar por uma velocidade específica. Os valores válidos são standard e fast:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
speeds[]=fast&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Limites de granularidade de tempo

Cost API

Recupere detalhamentos de custo em nível de serviço em USD com o endpoint /v1/organizations/cost_report.

Conceitos principais

• Moeda: Todos os custos em USD, reportados como strings decimais nas menores unidades (centavos)
• Tipos de custo: Rastreie custos de uso de tokens, busca na web e execução de código
• Agrupamento: Agrupe custos por workspace ou descrição para detalhamentos mais específicos. Ao agrupar por description, as respostas incluem campos analisados como model e inference_geo
• Intervalos de tempo: Apenas granularidade diária (1d)

Para detalhes completos de parâmetros e esquemas de resposta, consulte a referência da Cost API.

Exemplo básico

curl "https://api.anthropic.com/v1/organizations/cost_report?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
group_by[]=workspace_id&\
group_by[]=description" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Paginação

Ambos os endpoints suportam paginação para grandes conjuntos de dados:

1. Faça sua requisição inicial
2. Se has_more for true, use o valor de next_page na sua próxima requisição
3. Continue até que has_more seja false

# Primeira requisição
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

# A resposta inclui: "has_more": true, "next_page": "page_xyz..."

# Próxima requisição com paginação
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7&\
page=page_xyz..." \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Casos de uso comuns

Explore implementações detalhadas no Claude Cookbook:

• Relatórios de uso diário: Rastreie tendências de consumo de tokens
• Atribuição de custos: Aloque despesas por workspace para chargebacks
• Eficiência de cache: Meça e otimize o cache de prompt
• Monitoramento de orçamento: Configure alertas para limites de gastos
• Exportação CSV: Gere relatórios para equipes de finanças

Perguntas frequentes

Quão recentes são os dados?

Os dados de uso e custo normalmente aparecem dentro de 5 minutos após a conclusão da requisição à API, embora os atrasos possam ocasionalmente ser maiores.

Qual é a frequência de polling recomendada?

A API suporta polling uma vez por minuto para uso contínuo. Para rajadas curtas (por exemplo, baixar dados paginados), polling mais frequente é aceitável. Armazene os resultados em cache para dashboards que precisam de atualizações frequentes.

Como rastreio o uso de execução de código?

Os custos de execução de código aparecem no endpoint de custo agrupados sob Code Execution Usage no campo de descrição. A execução de código não está incluída no endpoint de uso.

Como rastreio o uso do Priority Tier?

Filtre ou agrupe por service_tier no endpoint de uso e procure pelo valor priority. Os custos do Priority Tier não estão disponíveis no endpoint de custo.

O que acontece com o uso do Workbench?

O uso da API a partir do Workbench não está associado a uma chave de API, então api_key_id será null mesmo ao agrupar por essa dimensão.

Como o workspace padrão é representado?

Uso e custos atribuídos ao workspace padrão têm um valor null para workspace_id.

Como obtenho detalhamentos de custo por usuário para o Claude Code?

Use a Claude Code Analytics API, que fornece custos estimados por usuário e métricas de produtividade sem as limitações de desempenho de detalhar custos por muitas chaves de API. Para uso geral da API com muitas chaves, use a Usage API para rastrear o consumo de tokens como um proxy de custo.

Veja também

As APIs de Uso e Custo podem ser usadas para ajudar você a oferecer uma melhor experiência para seus usuários, gerenciar custos e preservar seu limite de taxa. Saiba mais sobre alguns desses outros recursos:

• Admin API
• Referência da Admin API
• Preços
• Cache de prompt - Otimize custos com cache
• Processamento em lote - 50% de desconto em requisições em lote
• Limites de taxa - Entenda os níveis de uso
• Rate Limits API - Leia seus limites de taxa configurados
• Residência de dados - Controle a geografia de inferência