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
Grafana Cloud
Integração sem agente para observabilidade LLM fácil com dashboards e alertas prontos para uso
Honeycomb
Consulta avançada e visualização através do OpenTelemetry
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, ou1d) - 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_morefortrue, use o valornext_pageem sua próxima solicitação - Continue até que
has_moresejafalse
# 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