--- title: API de Uso e Custo url: https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-api description: Acesse programaticamente os dados de uso e custo da API da sua organização com a Admin API de Uso e Custo. --- **A Admin API não está disponível para contas individuais.** Para colaborar com colegas de equipe e adicionar membros, configure sua organização na página [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) no Claude Console. A Admin API de Uso e Custo fornece acesso programático e granular aos dados históricos de uso e custo da API da sua organização. Esses dados são semelhantes às informações disponíveis na página [Uso](https://platform.claude.com/usage) (`platform.claude.com/usage`) e na página [Custo](https://platform.claude.com/cost) (`platform.claude.com/cost`) no 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](https://platform.claude.com/docs/pt-BR/api/rate-limits):** Otimize recursos como [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) 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 **Credenciais da Admin API necessárias.** Estes endpoints fazem parte da Admin API. Você pode acessá-los usando uma [chave de API Admin](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api-keys), um token OAuth com o escopo `org:admin`, ou uma chave pessoal ou de conta de serviço que não esteja restrita a um workspace; chaves de API de workspace não funcionam. Consulte [Autenticação](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api#authentication) para mais detalhes. As organizações Claude Enterprise usam uma chave de API Analytics com uma API diferente; consulte [Qual API você precisa?](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-api#which-api-do-you-need). **Claude Platform na AWS:** Os endpoints programáticos da API de Uso e Custo não estão disponíveis atualmente. Visualize os dados de uso e custo nas páginas **Uso** e **Custo** no Claude Console. ## 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: | Sua organização | API | Tipo de chave | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude Console (Claude Platform) | A API Admin de Uso e Custo descrita nesta página | Chave de API Admin (`sk-ant-admin01-...`) ou outra [credencial da API Admin](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api#authentication) | | Claude Enterprise (claude.ai) | A [API Analytics do Claude Enterprise](https://platform.claude.com/docs/pt-BR/api/beta/organization/analytics) (endpoints de custo e uso) | Chave de API Analytics | 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](https://platform.claude.com/docs/pt-BR/manage-claude/analytics-api) 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. Plataforma de inteligência em nuvem para rastrear e prever custos Observabilidade de LLM com rastreamento e monitoramento automáticos Integração sem agente para observabilidade fácil de LLM com dashboards e alertas prontos para uso Plataforma de FinOps para gerenciamento de custos de nuvem e IA Consultas e visualizações avançadas por meio do OpenTelemetry Atribuição de uso e custo a itens de trabalho do Jira Plataforma de FinOps para observabilidade de custo e uso de LLM ## Início rápido Obtenha o uso diário da sua organização nos últimos 7 dias: ```bash cURL 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" ``` **Defina um cabeçalho User-Agent para integrações** Se você estiver criando uma integração, defina seu cabeçalho User-Agent para ajudar a Anthropic a entender os padrões de uso: ```text wrap 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 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](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency) ou velocidade, 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](https://platform.claude.com/docs/pt-BR/api/beta/organization/usage_report/retrieve_messages). ### Exemplos básicos #### Uso diário por modelo ```bash cURL 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 ```bash cURL 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-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 ```bash cURL 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" ``` Para recuperar os IDs das chaves de API da sua organização, use o endpoint [List API Keys](https://platform.claude.com/docs/pt-BR/api/organization/api_keys/list). Para recuperar os IDs dos workspaces da sua organização, use o endpoint [List Workspaces](https://platform.claude.com/docs/pt-BR/api/organization/workspaces/list) ou encontre os IDs dos workspaces da sua organização no Claude Console. #### Residência de dados Rastreie seus [controles de residência de dados](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency) 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. ```bash cURL 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`: ```bash cURL 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" ``` Modelos lançados antes de fevereiro de 2026 (anteriores ao Claude Opus 4.6 e Claude Sonnet 4.6) não suportam o parâmetro de requisição `inference_geo`, portanto seus relatórios de uso retornam `"not_available"` para esta dimensão. Você pode usar `not_available` como valor de filtro em `inference_geos[]` para direcionar esses modelos. #### Modo rápido Rastreie o uso do [modo rápido](https://platform.claude.com/docs/pt-BR/build-with-claude/fast-mode) agrupando e filtrando com a dimensão `speed`. Isso é útil para monitorar o uso do modo padrão versus o modo rápido. ```bash cURL 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 "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`: ```bash cURL 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 "x-api-key: $ANTHROPIC_ADMIN_KEY" ``` ### Limites de granularidade de tempo | Granularidade | Limite padrão | Limite máximo | Caso de uso | | ------------- | ------------- | ---------------- | --------------------------- | | `1m` | 60 intervalos | 1.440 intervalos | Monitoramento em tempo real | | `1h` | 24 intervalos | 168 intervalos | Padrões diários | | `1d` | 7 intervalos | 31 intervalos | 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 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](https://platform.claude.com/docs/pt-BR/api/beta/organization/cost_report/retrieve). Os custos do Priority Tier usam um modelo de faturamento diferente e não estão incluídos no endpoint de custo. Rastreie o uso do Priority Tier por meio do endpoint de uso. ### Exemplo básico ```bash cURL 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`. ```bash cURL # 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](https://platform.claude.com/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](https://platform.claude.com/docs/pt-BR/manage-claude/claude-code-analytics-api), 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](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-api#usage-api) 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](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api) * [Referência da API Admin](https://platform.claude.com/docs/pt-BR/api/beta/organization) * [APIs Analytics](https://platform.claude.com/docs/pt-BR/manage-claude/analytics-api) - Qual API analytics e tipo de chave sua organização precisa * [Preços](https://platform.claude.com/docs/pt-BR/about-claude/pricing) * [Cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) - Otimize custos com cache * [Processamento em lote](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing) - 50% de desconto em requisições em lote * [Limites de taxa](https://platform.claude.com/docs/pt-BR/api/rate-limits) - Entenda os níveis de uso * [API de Limites de Taxa](https://platform.claude.com/docs/pt-BR/manage-claude/rate-limits-api) - Leia seus limites de taxa configurados * [Residência de dados](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency) - Controle a geografia de inferência