API de Uso e Custo

A API Admin de Uso e Custo fornece acesso programático e granular a 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 de Uso e Custo 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: 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 limite de taxa: Otimize recursos como cache de prompt ou prompts específicos para aproveitar ao máximo sua capacidade alocada.
• Análise avançada: Realize análises de dados mais profundas do que as disponíveis no Console

As organizações Claude Enterprise usam uma chave de API Analytics com uma API diferente; consulte Qual API você precisa?.

Qual API você precisa?

A Anthropic fornece relatórios de custo e uso por meio de duas APIs, dependendo de qual produto Claude sua organização gerencia:

As organizações-mãe do Claude Enterprise não aparecem no Claude Console e não possuem chaves de API Admin, portanto, para elas, a chave de API Analytics é o único caminho para esses dados. Consulte APIs Analytics para saber como criar cada tipo de chave e a quais planos os dados de custo do Claude Enterprise se aplicam.

Soluções de parceiros

As principais plataformas de observabilidade oferecem integrações prontas para uso para monitorar o uso e o custo da sua API Claude, sem escrever código personalizado. Essas integrações fornecem dashboards, alertas e análises para ajudá-lo a gerenciar o uso da sua 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

API de Uso

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-chave

• Intervalos 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, janela de contexto, residência de dados ou velocidade (beta), e agrupe os resultados por essas dimensões
• Uso de ferramentas do 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 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "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-5&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "anthropic-version: 2023-06-01" \
  -H "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Você também pode filtrar para uma geografia 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Modo rápido (research preview)

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 versus o 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Você também pode filtrar para 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Limites de granularidade de tempo

API de Custo

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

Conceitos-chave

• Moeda: Todos os custos em USD, relatados 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 detalhados. 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 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "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 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "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..." \
  -H "anthropic-version: 2023-06-01" \
  -H "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 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 estão os dados?

Os dados de uso e custo normalmente aparecem dentro de 5 minutos após a conclusão da requisição da 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 sustentado. 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 o valor priority. Os custos do Priority Tier não estão disponíveis no endpoint de custo.

O que acontece com o uso do playground?

O uso da API a partir do playground no Claude Console (e do legado Workbench antes dele) não está associado a uma chave de API, portanto api_key_id será null mesmo ao agrupar por essa dimensão.

Como o workspace padrão é representado?

O uso e os 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 API Analytics do Claude Code, 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 API de Uso para rastrear o consumo de tokens como um proxy de custo.

Veja também

Use as APIs de Uso e Custo para oferecer uma melhor experiência aos seus usuários, gerenciar custos e preservar seu limite de taxa. Saiba mais sobre alguns desses outros recursos:

• API Admin
• Referência da API Admin
• APIs Analytics - Qual API analytics e tipo de chave sua organização precisa
• 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
• API de Limites de Taxa - Leia seus limites de taxa configurados
• Residência de dados - Controle a geografia de inferência