API de Uso e Custo

The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

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 Claude.

Esta API permite que você monitore, analise e otimize melhor suas implementações 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 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

Chave de API de administrador necessária

Esta API faz parte da API de Administração. Esses endpoints requerem uma chave de API de Administrador (começando com sk-ant-admin...) que difere das chaves de API padrão. Apenas membros da organização com função de administrador podem provisionar chaves de API de Administrador através do Console Claude.

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 de API de forma eficaz.

Datadog

Observabilidade LLM com rastreamento automático e monitoramento

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"

Defina um cabeçalho User-Agent para integrações

Se você está construindo uma integração, defina seu cabeçalho User-Agent para nos ajudar a entender padrões de uso:

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

Para recuperar os IDs de chave de API da sua organização, use o endpoint Listar Chaves de API.

Para recuperar os IDs de workspace da sua organização, use o endpoint Listar Workspaces, ou encontre os IDs de workspace da sua organização no Console Anthropic.

Limites de granularidade de tempo

Granularidade	Limite Padrão	Limite Máximo	Caso de Uso
`1m`	60 buckets	1440 buckets	Monitoramento em tempo real
`1h`	24 buckets	168 buckets	Padrões diários
`1d`	7 buckets	31 buckets	Relatórios semanais/mensais

API de Custo

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, 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
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.

Os custos do Nível de Prioridade usam um modelo de faturamento diferente e não estão incluídos no endpoint de custo. Rastreie o uso do Nível de Prioridade através do endpoint de uso em vez disso.

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:

Faça sua solicitação inicial
Se has_more for true, use o valor next_page em sua próxima solicitação
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. Armazene em cache os 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 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 Claude Code?

Use a API de Análise 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 de API com muitas chaves, use a API de Uso para rastrear o consumo de tokens como proxy de custo.

Veja também

As APIs de Uso e Custo podem ser usadas para ajudá-lo a oferecer 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