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 semelhantes às informações disponíveis nas páginas 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 exatas de tokens e padrões de uso em vez de depender apenas da contagem de tokens de resposta
Reconciliação de Custos: Corresponda registros internos com a cobrança 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: Realize análises de dados mais profundas do que o que está disponível no Console

Chave de API de Administração obrigatória

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

Soluções de parceiros

Plataformas de observabilidade líderes oferecem integrações prontas para uso para monitorar seu uso e custo da API Claude, sem escrever código personalizado. Essas integrações fornecem painéis, alertas e análises para ajudá-lo a gerenciar seu uso de API de forma eficaz.

CloudZero

Plataforma de inteligência em nuvem para rastreamento e previsão de custos

Início rápido

Obtenha o uso diário da sua organização dos ú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: YourApp/1.0.0 (https://yourapp.com)

API de Uso

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

Conceitos-chave

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 armazenada em cache, criação de cache e tokens de saída
Filtragem e agrupamento: Filtre por chave de API, espaço de trabalho, 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 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-opus-4-7&\
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 espaços de trabalho

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 espaço de trabalho da sua organização, use o endpoint Listar Espaços de Trabalho ou encontre os IDs de espaço de trabalho da sua organização no Console Anthropic.

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

Você também pode filtrar para uma geo 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: $ADMIN_API_KEY"

Modelos lançados antes de fevereiro de 2026 (antes do Claude Opus 4.6) não suportam o parâmetro de solicitação inference_geo, portanto seus relatórios de uso retornam "not_available" para essa dimensão. Você pode usar not_available como um valor de filtro em inference_geos[] para direcionar esses modelos.

Modo rápido (beta: visualização 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 versus 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: $ADMIN_API_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" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ADMIN_API_KEY"

Tanto o filtro speeds[] quanto o valor speed group_by requerem o cabeçalho beta fast-mode-2026-02-01.

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

Moeda: Todos os custos em USD, relatados como strings decimais em unidades mais baixas (centavos)
Tipos de custo: Rastreie custos de uso de tokens, pesquisa na web e execução de código
Agrupamento: Agrupe custos por espaço de trabalho ou descrição para detalhamentos detalhados. Ao agrupar por description, as respostas incluem campos analisados como model e inference_geo
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 cobrança 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.

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"

# A 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 Claude Cookbook:

Relatórios de uso diário: Rastreie tendências de consumo de tokens
Atribuição de custo: Aloque despesas por espaço de trabalho para cobranças
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

Qual é a atualidade dos dados?

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

Qual é a frequência de polling recomendada?

A API suporta polling uma vez por minuto para uso sustentado. Para rajadas curtas (por exemplo, download de dados paginados), polling mais frequente é aceitável. Armazene em cache os resultados para painéis 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 de API do Workbench não está associado a uma chave de API, portanto api_key_id será null mesmo ao agrupar por essa dimensão.

Como o espaço de trabalho padrão é representado?

O uso e os custos atribuídos ao espaço de trabalho 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 do Claude Code, que fornece custos estimados por usuário e métricas de produtividade sem as limitações de desempenho de dividir 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
Residência de dados - Controle a geografia da inferência