API de Uso e Custo

A API de Administração de Uso e Custo fornece acesso programático e granular aos dados históricos de uso e custo da API para sua organização. Esses dados são similares às informações disponíveis nas páginas de Uso e Custo do Console Anthropic.

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: Combine 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 limites de taxa e Nível de Prioridade: Otimize recursos como cache de prompt ou prompts específicos para aproveitar ao máximo sua capacidade alocada, ou compre capacidade dedicada.
• Análise Avançada: Execute 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 seu uso e custo da API Claude, sem escrever código personalizado. Essas integrações fornecem dashboards, alertas e análises para ajudá-lo a gerenciar seu uso da API de forma eficaz.

​

Início rápido

Obtenha o uso diário da sua organização para os ú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: $ADMIN_API_KEY"

User-Agent: SeuApp/1.0.0 (https://seuapp.com)

​

API de Uso

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

​

Conceitos principais

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

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

​

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: $ADMIN_API_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-sonnet-4-20250514&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

​

Limites de granularidade de tempo

​

API de Custo

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

​

Conceitos principais

• Moeda: Todos os custos em USD, relatados como strings decimais nas menores unidades (centavos)
• Tipos de custo: Rastreie custos de uso de tokens, pesquisa na web e execução de código
• Agrupamento: Agrupe custos por workspace ou descrição para detalhamentos detalhados
• Buckets de tempo: Apenas granularidade diária (1d)

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

​

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: $ADMIN_API_KEY"

​

Paginação

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

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

# Primeira solicitaçã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: $ADMIN_API_KEY"

# Resposta inclui: "has_more": true, "next_page": "page_xyz..."

# Próxima solicitaçã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: $ADMIN_API_KEY"

​

Casos de uso comuns

Explore implementações detalhadas no anthropic-cookbook:

• Relatórios de uso diário: Rastreie tendências de consumo de tokens
• Atribuição de custos: Aloque despesas por workspace para estornos
• 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 atualizados são os dados?

Os dados de uso e custo normalmente aparecem dentro de 5 minutos da conclusão da solicitação da API, embora atrasos possam ocasionalmente ser maiores.

​

Qual é a frequência de polling recomendada?

A API suporta polling uma vez por minuto para uso sustentado. Para rajadas curtas (por exemplo, baixar dados paginados), polling mais frequente é aceitável. Faça cache dos resultados 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 Nível de Prioridade?

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

​

O que acontece com o uso do Workbench?

O uso da API do Workbench não está associado a uma chave de API, então api_key_id será null mesmo quando agrupando 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.

​

Veja também

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

• Visão geral da API de Administração
• Referência da API de Administração
• Preços
• Cache de prompt - Otimize custos com cache
• Processamento em lote - 50% de desconto em solicitações em lote
• Limites de taxa - Entenda os níveis de uso