API de Análise de Uso e Custo

A API de Análise de Uso e Custo informa o uso histórico de tokens e o custo da sua organização, detalhados pelas dimensões que você escolher, como modelo, workspace, chave de API ou o usuário ou conta de serviço por trás de cada solicitação. Para organizações do Claude Console, esses dados são semelhantes aos que as páginas Usage e Cost do Claude Console mostram.

A API tem dois endpoints:

• GET /v1/organizations/analytics/usage informa contagens de tokens e contagens de solicitações.
• GET /v1/organizations/analytics/cost informa o custo em USD.

A API de Análise de Uso e Custo está em beta. Envie o cabeçalho anthropic-beta: analytics-usage-cost-2026-08-24 e um cabeçalho anthropic-version em cada solicitação. O SDK e a CLI ant enviam ambos os cabeçalhos para você e buscam as páginas restantes à medida que você lê os resultados, então limit define apenas o tamanho da página.

Use esta API para:

• Atribuir gastos: Detalhe o custo e o uso de tokens por workspace, chave de API, modelo, nível de serviço ou pela identidade que fez cada solicitação.
• Encontrar os maiores consumidores: Classifique os resultados por tokens, solicitações ou custo para responder a perguntas como “quais chaves de API gastam mais este mês?”
• Criar séries temporais: Divida os resultados em buckets diários, por hora ou por minuto para dashboards e relatórios financeiros.
• Integrar uma única vez: Os mesmos endpoints, parâmetros e campos de resposta atendem organizações do Claude Console e do Claude Enterprise.

Início rápido

Obtenha o uso diário de tokens da primeira semana de setembro, uma linha para cada modelo e dia:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=10,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

A resposta tem uma linha para cada modelo e dia que tem uso, com o maior total_tokens primeiro. Este exemplo mostra uma única linha:

{
  "data": [
    {
      "starting_at": "2026-09-03T00:00:00Z",
      "ending_at": "2026-09-04T00:00:00Z",
      "group": {
        "product": null,
        "model": "claude-sonnet-5",
        "context_window": null,
        "inference_geo": null,
        "speed": null,
        "slack_channel_id": null,
        "claude_tag_category": null,
        "claude_tag_user_id": null,
        "rbac_group_id": null,
        "workspace_id": null,
        "service_tier": null,
        "user_profile_id": null,
        "agent_id": null,
        "environment_id": null,
        "deployment_id": null,
        "session_id": null,
        "actor": null,
        "actor_type": null,
        "api_key_id": null
      },
      "usage": {
        "uncached_input_tokens": 1284500,
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 215300
        },
        "cache_read_input_tokens": 3200000,
        "output_tokens": 891000,
        "total_tokens": 5590800,
        "server_tool_use": {
          "web_search_requests": 12
        },
        "requests": 4210
      }
    }
  ],
  "has_more": true,
  "next_page": "page_V2mQ4dkt9HcbX3pLr...",
  "data_refreshed_at": "2026-09-18T16:02:11Z"
}

Como os resultados são estruturados

• Toda linha tem três partes: starting_at e ending_at indicam o período que a linha abrange, group contém todas as dimensões e usage (ou cost no endpoint de custo) contém as métricas.
• Dimensões são nulas a menos que agrupadas: Uma dimensão em group é null a menos que você a liste em group_by[]. Uma dimensão agrupada também é null em linhas que não têm valor para ela, como model no uso de execução de código. group_by[] aceita até cinco dimensões.
• Uma linha para cada combinação: Cada linha é uma combinação das dimensões agrupadas, e toda combinação que tem uso ou custo aparece exatamente uma vez nas páginas de uma consulta. Sem group_by[] e sem time_bucket_width, a resposta é uma única linha que totaliza todo o intervalo.
• Time buckets são opcionais: Defina time_bucket_width como 1m, 1h ou 1d para dividir cada combinação por bucket UTC; o starting_at e o ending_at de cada linha passam a ser os limites do seu bucket. Buckets sem uso ou custo não produzem linhas.
• Classificadas por padrão: As linhas são ordenadas pela métrica de order_by em todo o intervalo, da maior para a menor por padrão (order=asc inverte a ordem). Para construir uma série temporal, defina time_bucket_width e order_by=time. As linhas então retornam um time bucket após o outro, com o time bucket mais recente primeiro por padrão (order=asc coloca o mais antigo primeiro), com as maiores linhas primeiro dentro de cada time bucket. Preencha os time buckets vazios com zeros.
• Filtros funcionam junto com o agrupamento: A maioria das dimensões pelas quais você pode agrupar tem um filtro de lista correspondente em notação de colchetes, como models[]=claude-opus-5-5. Repita o parâmetro para passar vários valores, até 100. Vários valores para o mesmo filtro são combinados com OR, e filtros diferentes são combinados com AND. Filtros e group_by[] são independentes; você pode filtrar por qualquer dimensão agrupando ou não por ela, ou o inverso.

Dimensões como model e actor se aplicam a todas as organizações. Algumas, como api_key_id, se aplicam apenas a organizações do Claude Console, e outras, como slack_channel_id, se aplicam apenas a organizações do Claude Enterprise. Uma dimensão que não se aplica à sua organização é null em todas as linhas e seu filtro não corresponde a nada; a exceção é rbac_group_id, que retorna um erro quando equipes não estão disponíveis para sua organização. A referência da API para uso e custo lista todas as dimensões, filtros e valores.

Atores

A dimensão actor indica a quem uma solicitação é atribuída: um usuário, uma conta de serviço, uma identidade de nuvem federada (um principal da AWS ou do Google Cloud, para organizações que acessam o Claude por meio de sua plataforma de nuvem) ou, quando nenhum desses está por trás da solicitação, a própria chave de API. Quando você agrupa por actor, o actor de cada linha é um objeto cujo type indica de que tipo ele é. O uso que não pode ser atribuído a nenhuma identidade tem actor: null.

Chaves pessoais e chaves de conta de serviço atuam como o usuário ou a conta de serviço aos quais estão vinculadas, então suas solicitações mostram essa identidade como o actor e a chave em api_key_id. Chaves de workspace legadas não estão vinculadas a uma identidade, então a chave aparece tanto como o actor quanto como o api_key_id. A exceção é a chave que o Claude Code cria quando um membro faz login com sua conta do Claude Console: ela fica no workspace do Claude Code, e seu uso é atribuído a esse membro. Solicitações feitas sem uma chave de API, como a partir do Claude Console ou com um token de Workload Identity Federation, têm api_key_id: null; o actor de uma carga de trabalho federada é sua conta de serviço. Para incluir o uso sem chave de API em um filtro api_key_ids[], adicione uma entrada vazia: api_key_ids[]=.

Os filtros api_key_ids[] e actor_ids[] respondem a perguntas diferentes. api_key_ids[]=apikey_... corresponde a todas as solicitações que a chave autenticou, independentemente de a quem sejam atribuídas. actor_ids[]=apikey_... corresponde apenas às solicitações atribuídas à própria chave.

Endpoint de uso

GET /v1/organizations/analytics/usage retorna contagens de tokens por tipo. order_by aceita total_tokens (o padrão), output_tokens, uncached_input_tokens, requests ou time.

Por exemplo, para ver uma semana de uso de um workspace e uma chave de API, detalhado por nível de serviço (uma linha para cada nível, abrangendo a semana inteira):

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    api_key_ids=["apikey_01Rj2N8SVvo6BePZj99NhmiT"],
    group_by=["service_tier"],
)

for row in rows:
    print(f"{row.group.service_tier}: {row.usage.total_tokens}")

Para consultar IDs de chaves de API e de workspaces, use os endpoints List API Keys e List Workspaces ou o Claude Console.

Para descobrir quais usuários, contas de serviço e chaves de API fizeram mais solicitações em um mês:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["actor"],
    order_by="requests",
    limit=25,
)

for row in rows:
    print(f"{row.group.actor}: {row.usage.requests}")

Endpoint de custo

GET /v1/organizations/analytics/cost aceita os mesmos filtros, dimensões e time buckets que o endpoint /usage. O objeto cost de cada linha contém amount (o custo após descontos e antes da aplicação de quaisquer créditos), list_amount (o custo a preços de tabela), currency (sempre "USD") e requests. Os valores são strings decimais em centavos com seis casas decimais: "41280.000000" equivale a $412,80 USD. order_by aceita amount (o padrão), list_amount ou time.

Duas dimensões extras existem apenas neste endpoint e não contam para o limite de cinco dimensões: group_by[]=cost_type divide cada linha em uma linha para cada tipo de custo, e group_by[]=token_type divide o custo de tokens em uma linha para cada tipo de token. limit também não se aplica a essas duas dimensões, então uma página pode conter mais de limit linhas. Por exemplo, custo por modelo, tipo de custo e tipo de token para um mês:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["model", "cost_type", "token_type"],
)

for row in rows:
    print(
        f"{row.group.model} {row.group.cost_type} {row.group.token_type}: {row.cost.amount}"
    )

Para cada modelo, a resposta tem cinco linhas tokens (uma para cada tipo de token) mais uma linha para cada um de web_search, code_execution e session_usage. Uma dessas linhas:

{
  "starting_at": "2026-09-01T00:00:00Z",
  "ending_at": "2026-10-01T00:00:00Z",
  "group": {
    "model": "claude-opus-5",
    ...,
    "cost_type": "tokens",
    "token_type": "cache_read_input_tokens"
  },
  "cost": {
    "currency": "USD",
    "amount": "41280.000000",
    "list_amount": "51600.000000",
    "requests": null
  }
}

O objeto group contém todas as dimensões e está abreviado aqui. Com group_by[]=cost_type ou token_type especificado, requests é null em todas as linhas.

Intervalos de datas e time buckets

• Os timestamps seguem o RFC 3339 com um deslocamento UTC, por exemplo 2026-09-01T00:00:00Z. starting_at é inclusivo e ending_at é exclusivo.
• starting_at deve ser em ou após 1º de janeiro de 2026 e dentro dos últimos 365 dias. Uma solicitação pode abranger no máximo 31 dias; ending_at tem como padrão 31 dias após starting_at ou o horário atual, o que ocorrer primeiro.
• ending_at é obrigatório sempre que time_bucket_width estiver definido, e com time_bucket_width=1m uma solicitação pode abranger no máximo 24 horas.
• Ambas as extremidades do intervalo são arredondadas para baixo até um limite de bucket UTC, ou até a hora quando time_bucket_width não está definido. Por exemplo, com time_bucket_width=1h, um starting_at de 2026-09-01T10:43:00Z é tratado como 2026-09-01T10:00:00Z e um ending_at de 2026-09-01T15:43:00Z como 2026-09-01T15:00:00Z, então a resposta cobre das 10:00 às 15:00 UTC.

Atualização dos dados

Toda resposta inclui um timestamp data_refreshed_at, e o uso posterior a esse momento está ausente ou parcial. Quando ainda não há dados disponíveis para nenhuma parte do intervalo solicitado, data_refreshed_at é null e data fica vazio. Os dados normalmente são atualizados em até 4 horas após o uso subjacente e podem levar até 24 horas. Os valores podem ser revisados à medida que eventos atrasados chegam e a reconciliação é executada, até cerca de 7 dias após o fim do mês civil. Por exemplo, os valores de 1º de outubro podem mudar até cerca de 7 de novembro. Para obter resultados estáveis em chamadas repetidas, defina ending_at em ou antes de um data_refreshed_at que você já tenha visto; para totais finais, consulte apenas meses que terminaram há pelo menos 7 dias. Todas as páginas de uma consulta paginada leem o mesmo snapshot de dados, então data_refreshed_at é idêntico em todas as páginas.

Migrar da API de Uso e Custo

Esta seção é para organizações do Claude Console que chamam a API de Uso e Custo legada (/v1/organizations/usage_report/messages e /v1/organizations/cost_report). Sua chave de Admin API, o cabeçalho anthropic-version, starting_at e ending_at, os valores de largura de bucket (1m, 1h, 1d), a notação de colchetes, os nomes dos campos de paginação e os nomes dos campos de tokens e custo permanecem os mesmos. O que muda:

Para reproduzir o relatório diário legado, solicite time_bucket_width=1d com o mesmo group_by[], percorra as páginas com limit=1000 e, em seguida, agrupe as linhas por starting_at e preencha os dias ausentes com zeros. Adicione order_by=time&order=asc para obter os dias em ordem. Uso diário por modelo durante 1 semana, antes:

curl --globoff "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

e depois:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=1000,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

Custo diário por workspace, modelo, nível de serviço, janela de contexto e geografia de inferência, dividido por tipo de custo e tipo de token:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=[
        "workspace_id",
        "model",
        "service_tier",
        "context_window",
        "inference_geo",
        "cost_type",
        "token_type",
    ],
    limit=1000,
)

for row in rows:
    group = row.group
    print(
        f"{row.starting_at} {group.workspace_id} {group.model} {group.service_tier} "
        f"{group.context_window} {group.inference_geo} {group.cost_type} {group.token_type}: "
        f"{row.cost.amount}"
    )

Migrar dos relatórios de uso e custo do Claude Enterprise

Esta seção é para organizações do Claude Enterprise que chamam os endpoints de relatório da Claude Enterprise Analytics API usage_report, cost_report, user_usage_report e user_cost_report em /v1/organizations/analytics/. Esses endpoints são legados e continuam sendo suportados. Migre para /analytics/usage e /analytics/cost quando quiser qualquer um dos seguintes:

• Todos os grupos em cada time bucket, em vez dos 100 principais grupos em cada bucket
• Agrupamento por actor ou actor_type junto com outras dimensões, tanto em uso quanto em custo
• Linhas classificadas por uma métrica de sua escolha em todo o intervalo, ou ordenadas por time bucket
• Uma única integração que também atende organizações do Claude Console

Sua chave, a data mais antiga, o período retroativo de 365 dias e o intervalo de 31 dias, os nomes e valores de filtros e dimensões (exceto user_ids[] e o valor de produto do Claude Tag), os campos actor de usuário, os campos de métricas e valores, data_refreshed_at, as regras de cursor e o limite de taxa no nível da organização permanecem os mesmos. O único cabeçalho novo é o cabeçalho beta analytics-usage-cost-2026-08-24. O que muda:

Custo por usuário em um mês, antes:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.user_cost_report.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    limit=100,
)

for row in rows:
    print(f"{row.actor.user_id}: {row.amount}")

e depois, adicionando um detalhamento por produto:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    actor_types=["user_actor"],
    group_by=["actor", "product"],
    limit=100,
)

for row in rows:
    actor = row.group.actor
    if actor is not None and actor.type == "user_actor":
        print(f"{actor.user_id} {row.group.product}: {row.cost.amount}")

Perguntas frequentes

Como o workspace padrão é representado?

O workspace padrão de uma organização do Claude Console tem seu próprio ID wrkspc_, como qualquer outro workspace. As linhas do workspace padrão têm esse ID em workspace_id, e você pode filtrar por ele com workspace_ids[]. List Workspaces omite o workspace padrão, a menos que você passe include_default=true. Para verificar se um workspace_id desconhecido é o workspace padrão, passe-o para Get Workspace: o workspace padrão retorna "name": "Default".

Como obtenho o custo por usuário do Claude Code?

Chame o endpoint de custo com products[]=claude_code&group_by[]=actor. Organizações do Claude Console também podem usar a Claude Code Analytics API, que informa a atividade do Claude Code por usuário e o custo estimado.

Veja também

• API de Uso e Custo (legado)
• APIs de Analytics: de qual API de Analytics e de qual tipo de chave sua organização precisa
• Claude Code Analytics API
• Referência da Admin API
• Preços