Consultando Uso por Chave de API e Workspace com a API de Administração
Filtre dados históricos de uso e custo para uma única chave de API ou workspace.
Resumo
A maioria das perguntas sobre custos não é "quanto gastamos no total", mas sim "quanto esta equipe gastou".
A API de Administração responde a isso permitindo que você filtre e agrupe relatórios de uso e custo por api_key_id e workspace_id.
A filtragem restringe o conjunto de resultados a um ou poucos identificadores antes mesmo que a API compute o relatório.
O agrupamento mantém as linhas de cada identificador visíveis lado a lado, o que geralmente é a melhor opção quando você tem mais de uma chave ou workspace para comparar.
Esta página cobre ambos, além de como resolver um nome de chave ou workspace legível por humanos para o ID que a API espera.
Receita
import anthropic
client = anthropic.Anthropic() # lê ANTHROPIC_ADMIN_KEY do env
# Filtrar: uso para uma chave de API específica
by_key = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
api_key_ids=["apikey_01A2B3C4"],
)
# Filtrar: uso para um workspace específico
by_workspace = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
workspace_ids=["wksp_01abc123"],
)
# Agrupar: uso detalhado por chave, sem filtro aplicado
grouped = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
group_by=["api_key_id"],
)Quando usar isso:
- Você está investigando um pico de custo e suspeita que ele se origina de uma integração.
- Você precisa de um número por chave ou por workspace para um relatório de rateio ou orçamento.
- Você está auditando quais chaves ainda estão ativas antes de revogar as não utilizadas.
- Você quer um ranking dos maiores gastadores em sua organização, não um total único.
Exemplo de Trabalho
import anthropic
from datetime import datetime, timedelta, timezone
client = anthropic.Anthropic()
def usage_for_key(api_key_id: str, days: int = 30) -> dict:
"""Retorna o uso total de tokens para uma chave de API nos últimos N dias."""
start = (datetime.now(timezone.utc) - timedelta(days=days)).isoformat()
report = client.beta.usage.report(
starting_at=start,
api_key_ids=[api_key_id],
bucket_width="1d",
)
totals = {
"uncached_input_tokens": 0,
"cached_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 0,
}
for bucket in report.data:
totals["uncached_input_tokens"] += bucket.uncached_input_tokens
totals["cached_input_tokens"] += bucket.cached_input_tokens
totals["cache_creation_input_tokens"] += bucket.cache_creation_input_tokens
totals["output_tokens"] += bucket.output_tokens
return totals
def top_workspaces_by_output(days: int = 30, limit: int = 5) -> list[tuple[str, int]]:
"""Classifica os workspaces por volume de tokens de saída nos últimos N dias."""
start = (datetime.now(timezone.utc) - timedelta(days=days)).isoformat()
report = client.beta.usage.report(
starting_at=start,
group_by=["workspace_id"],
)
ranked = sorted(
((bucket.workspace_id, bucket.output_tokens) for bucket in report.data),
key=lambda pair: pair[1],
reverse=True,
)
return ranked[:limit]
if __name__ == "__main__":
print(usage_for_key("apikey_01A2B3C4"))
for workspace_id, output_tokens in top_workspaces_by_output():
print(workspace_id, output_tokens)O que isso demonstra:
usage_for_keymostra um filtro de identificador único usado para responder "quanto custou esta chave".top_workspaces_by_outputmostra o agrupamento usado para classificar vários identificadores ao mesmo tempo, sem filtrar nenhum deles.- Ambas as funções acumulam totais de tipos de token separadamente em vez de colapsá-los, para que o chamador ainda possa aplicar preços por tipo posteriormente.
bucket_width="1d"impede que o relatório retorne uma única linha total gigante quando você pode querer uma tendência posteriormente.
Mergulho Profundo
Como Funciona
api_key_idseworkspace_idssão ambos filtros do tipo lista; passar múltiplos valores retorna o uso para qualquer um deles, não apenas para o primeiro.- A filtragem ocorre antes da agregação, portanto, um relatório filtrado é mais barato de raciocinar e geralmente mais rápido do que buscar tudo e filtrar no lado do cliente.
group_bye os parâmetros de filtro se compõem: você pode filtrar para um punhado de workspaces e ainda agrupar o resultado por chave de API dentro deles.- IDs, não nomes, são o que a API aceita. Um workspace chamado "Equipe de Crescimento" e um ID de workspace como
wksp_01abc123são coisas diferentes, e apenas o ID é um valor de filtro válido.
Resolvendo Nomes para IDs
| Você tem | Você precisa | Como obter |
|---|---|---|
| Um nome de workspace mostrado no Console | workspace_id | Liste os workspaces via endpoint de workspace da API de Administração, ou copie o ID da página de configurações do workspace no Console |
| O rótulo de exibição de uma chave | api_key_id | Liste as chaves de API via endpoint de chaves de API da API de Administração; o rótulo e o ID são retornados juntos |
| Apenas um total de custo parcial da interface do usuário do Console | Ambos | Cruzar a página de uso do Console, que mostra nome e ID ao clicar em um workspace ou chave |
import anthropic
client = anthropic.Anthropic()
# Resolver o nome legível por humanos de um workspace para o ID que a API de uso espera
workspaces = client.beta.admin.workspaces.list()
target = next(w for w in workspaces.data if w.name == "Equipe de Crescimento")
print(target.id) # use este valor como filtro workspace_idsNotas do Python
# Construir uma lista de filtros dinamicamente é um padrão comum quando os IDs de chave
# vêm de seu próprio banco de dados em vez de serem codificados.
active_key_ids: list[str] = load_active_key_ids_from_db()
report = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
api_key_ids=active_key_ids or None, # None significa "sem filtro" para o SDK
)Parâmetros e Valores de Retorno
| Parâmetro | Tipo | Descrição |
|---|---|---|
api_key_ids | list[str] | Restrinja o relatório a um ou mais IDs de chave de API. |
workspace_ids | list[str] | Restrinja o relatório a um ou mais IDs de workspace. |
group_by | list[str] | Retorne uma linha por combinação única dessas dimensões, por exemplo, ["api_key_id"]. |
starting_at | str (ISO 8601) | Início da janela do relatório, obrigatório. |
ending_at | str (ISO 8601) | Fim da janela do relatório, opcional, padrão é agora. |
Armadilhas
- Passar um rótulo de chave em vez de um ID.
api_key_idsaceita apenas o ID da chave, não seu nome de exibição. Correção: liste as chaves de API primeiro e leia o campoid, ou armazene o ID ao lado do rótulo em seu próprio sistema. - Filtrar e agrupar no mesmo campo e esperar um resultado filtrado e não agrupado. Se você filtrar para um workspace e também agrupar por
workspace_id, obterá um resultado agrupado de linha única, o que é inofensivo, mas redundante. Correção: agrupe apenas por um campo quando tiver mais de um valor dele em escopo. - Assumir que um resultado vazio significa que a chave nunca existiu. Um relatório vazio significa com frequência que a chave teve uso zero naquela janela. Correção: verifique a existência da chave separadamente através do endpoint de chaves da API de Administração antes de concluir que ela é inválida.
- Esquecer que uma chave excluída ou rotacionada ainda tem uso histórico. Os dados de uso persistem após uma chave ser revogada. Correção: mantenha um mapeamento local do ID da chave para o rótulo mesmo após a rotação, para que relatórios antigos permaneçam legíveis.
- Construir uma lista enorme de
api_key_idspara contornar a falta de um filtro "não no workspace X". A API filtra por inclusão, não por exclusão. Correção: busque todas as chaves da organização, subtraia as que você deseja excluir em Python e passe o restante como filtro. - Reexecutar um relatório por chave em um loop, uma vez por chave. Isso multiplica as chamadas de API desnecessariamente. Correção: use
group_by=["api_key_id"]em uma única chamada em vez de N chamadas filtradas separadas.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
Filtrar por api_key_ids / workspace_ids | Você já sabe exatamente qual chave ou workspace lhe interessa | Você precisa comparar mais do que um punhado de identificadores, pois o agrupamento escala melhor |
Agrupar por api_key_id / workspace_id | Você quer o uso de cada identificador visível de uma vez, por exemplo, um ranking | Você se importa apenas com um identificador específico e quer a menor resposta possível |
| Páginas de Uso e Custo do Console, filtradas na interface | Uma consulta manual única, sem necessidade de código | Você precisa disso em uma programação recorrente ou associado a outros dados de negócios |
FAQs
Qual é a diferença entre filtrar por workspace_ids e agrupar por workspace_id?
- Filtrar (
workspace_ids=[...]) restringe o relatório apenas aos workspaces que você lista, retornando menos linhas. - Agrupar (
group_by=["workspace_id"]) mantém todos os workspaces em escopo, mas divide o resultado em uma linha por workspace. - Use a filtragem quando você sabe exatamente quem está procurando; use o agrupamento quando quiser comparar muitos.
Posso filtrar por api_key_ids e workspace_ids na mesma solicitação?
Sim. Ambos os filtros podem ser aplicados juntos, e a API retorna o uso que corresponde a ambas as condições. Isso é útil para restringir a uma chave específica que pertence a um workspace específico quando os IDs de chave sozinhos não são únicos o suficiente para seu caso de uso.
Como encontro o ID de uma chave de API se só sei seu rótulo no Console?
import anthropic
client = anthropic.Anthropic()
keys = client.beta.admin.api_keys.list()
match = next(k for k in keys.data if k.name == "backend-prod")
print(match.id)Filtrar por chave de API também filtra dados de custo, ou apenas dados de uso?
Ambos. Os mesmos filtros api_key_ids e workspace_ids se aplicam ao endpoint de relatório de custo, bem como ao endpoint de relatório de uso, pois o custo é derivado dos mesmos registros subjacentes.
O que acontece se eu passar um ID de chave de API que não existe?
A chamada de relatório é bem-sucedida, mas não retorna dados para esse ID, em vez de gerar um erro. Isso vale a pena tratar explicitamente se você estiver construindo automação que deve alertar sobre um ID de chave ausente ou digitado incorretamente.
Posso consultar o uso de uma chave que foi revogada?
Sim. Os registros de uso histórico estão vinculados ao ID da chave e persistem independentemente de a chave ainda estar ativa, portanto, as chaves revogadas permanecem consultáveis enquanto a janela de retenção de dados de sua organização cobrir.
Existe um limite para quantos IDs de chave de API posso passar em um filtro?
A lista aceita múltiplos IDs, mas listas muito grandes são melhor tratadas com agrupamento em vez de uma lista de filtros enorme. Se você estiver filtrando mais do que algumas dezenas de chaves, mude para group_by=["api_key_id"] e filtre posteriormente em Python.
Como combino um filtro de workspace com um detalhamento por modelo?
report = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
workspace_ids=["wksp_01abc123"],
group_by=["model"],
)Isso filtra para um workspace e, em seguida, agrupa as linhas restantes por modelo.
Por que agrupar por api_key_id em vez de apenas buscar o uso de cada chave separadamente?
Uma única chamada agrupada é uma viagem de ida e volta de rede e uma consulta contra os dados subjacentes, em vez de N chamadas para N chaves. Ela também garante que os dados de cada chave venham da mesma janela de tempo exata, o que é importante quando você está construindo um relatório que precisa somar corretamente.
Os IDs de workspace e os IDs de chave de API usam o mesmo formato?
Não, eles usam prefixos distintos (por exemplo, IDs de workspace geralmente começam com wksp_ e IDs de chave de API com apikey_), o que torna fácil capturar um valor de filtro misturado em um relance durante a revisão de código.
Posso filtrar por uma equipe ou departamento em vez de um workspace ou chave?
Não diretamente, a API entende apenas ID de chave de API e ID de workspace como filtros de identidade. Se sua organização mapeia equipes para workspaces ou um conjunto de chaves, você constrói esse mapeamento sozinho e o aplica em seu próprio código após buscar o relatório agrupado.
Devo filtrar no lado do servidor com os parâmetros da API, ou buscar tudo e filtrar em Python?
Filtre no lado do servidor com api_key_ids ou workspace_ids sempre que souber o alvo com antecedência. Isso reduz a quantidade de dados transferidos e a quantidade de agregação que a API precisa fazer, e mantém seu código Python mais simples, pois não está reimplementando a lógica de filtragem que a API já fornece.
Relacionados
- Como a API de Administração de Uso e Custo Modela Seu Gasto - o modelo de bucket de tokens em que esses filtros fatiam.
- Noções Básicas de Rastreamento de Uso e Custo - o relatório não filtrado em que esta página se baseia.
- Construindo um Painel de Custos a partir de Detalhamentos de Tokens Não Armazenados em Cache, Armazenados em Cache e de Saída - transforme um relatório filtrado ou agrupado em um painel.
- Filtrando Uso por Modelo, Nível de Serviço e Residência de Dados - as outras dimensões nas quais você pode fatiar além de chave e workspace.
- Modelo ADR: Um Modelo de Rateio para Uso de Chave de API Multi-Equipe - como a filtragem por chave alimenta uma política de rateio real.
Versões da Stack: Escrito com base na linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.