Filtrando Uso por Modelo, Nível de Serviço e Residência de Dados
Divida os dados de uso por versão de modelo, nível de serviço e residência de dados para relatórios de conformidade.
Resumo
Perguntas sobre custo e conformidade não param em "quem gastou isso".
Elas frequentemente continuam com "qual modelo", "sob qual nível de processamento" e "em qual região esses dados foram tratados".
A Admin API expõe todas as três como dimensões de filtro e agrupamento, juntamente com os filtros de chave de API e workspace abordados em outras partes desta seção.
Modelo e nível de serviço são principalmente questões de custo: modelos e níveis diferentes têm preços por token diferentes.
Residência de dados é principalmente uma questão de conformidade: algumas organizações são contratualmente ou legalmente obrigadas a saber, e às vezes restringir, onde seus dados de solicitação foram processados.
Receita
import anthropic
client = anthropic.Anthropic()
# Agrupar uso por modelo, para que você possa ver o gasto por modelo lado a lado
by_model = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
group_by=["model"],
)
# Filtrar para um único nível de serviço
by_tier = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
service_tiers=["batch"],
)
# Agrupar por região de residência de dados para uma exportação de conformidade
by_region = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
group_by=["data_residency"],
)Quando usar isso:
- Você quer ver se um mês caro foi impulsionado pela mistura de modelos (mais Opus, menos Haiku) em vez do volume bruto de solicitações.
- Você está decidindo se o nível de serviço batch ou priority vale a diferença de preço para uma determinada carga de trabalho.
- O departamento jurídico ou de conformidade precisa de um relatório de quais regiões processaram os dados de solicitação da sua organização durante um determinado período.
- Você está validando que um compromisso de residência de dados feito a um cliente está realmente sendo cumprido na prática.
Exemplo de Trabalho
"""
model_tier_region_report.py
Produz três detalhamentos lado a lado para uma revisão mensal: gasto por
modelo, gasto por nível de serviço e volume de solicitações por região de
residência de dados, útil para uma leitura mensal combinada de custo e conformidade.
"""
import anthropic
client = anthropic.Anthropic()
START = "2026-06-01T00:00:00Z"
END = "2026-06-30T23:59:59Z"
def total_tokens(bucket) -> int:
return (
bucket.uncached_input_tokens
+ bucket.cached_input_tokens
+ bucket.cache_creation_input_tokens
+ bucket.output_tokens
)
def spend_by_model() -> list[tuple[str, int]]:
report = client.beta.usage.report(starting_at=START, ending_at=END, group_by=["model"])
return sorted(
((bucket.model, total_tokens(bucket)) for bucket in report.data),
key=lambda pair: pair[1],
reverse=True,
)
def spend_by_service_tier() -> list[tuple[str, int]]:
report = client.beta.usage.report(starting_at=START, ending_at=END, group_by=["service_tier"])
return sorted(
((bucket.service_tier, total_tokens(bucket)) for bucket in report.data),
key=lambda pair: pair[1],
reverse=True,
)
def volume_by_residency() -> list[tuple[str, int]]:
report = client.beta.usage.report(starting_at=START, ending_at=END, group_by=["data_residency"])
return sorted(
((bucket.data_residency, total_tokens(bucket)) for bucket in report.data),
key=lambda pair: pair[1],
reverse=True,
)
if __name__ == "__main__":
print("Por modelo:")
for model, tokens in spend_by_model():
print(f" {model:<30}{tokens:>15,} tokens")
print("\nPor nível de serviço:")
for tier, tokens in spend_by_service_tier():
print(f" {tier:<30}{tokens:>15,} tokens")
print("\nPor região de residência de dados:")
for region, tokens in volume_by_residency():
print(f" {region:<30}{tokens:>15,} tokens")O que isso demonstra:
- Cada função agrupa por exatamente uma dimensão, o que mantém a saída de cada função legível e útil independentemente.
total_tokenssoma todos os quatro tipos de token apenas para a chave de ordenação, enquanto o relatório subjacente ainda preserva o detalhamento por tipo, se você precisar dele mais tarde.- Os três relatórios podem ser executados independentemente ou combinados em uma única leitura mensal que cobre tanto um ângulo de custo quanto um ângulo de conformidade.
- A ordenação decrescente expõe os maiores impulsionadores de custo ou volume primeiro, que é geralmente o que um revisor quer ver no topo.
Mergulho Profundo
Como Funciona
group_by=["model"]retorna uma linha por string de modelo distinta que sua organização realmente usou na janela, não uma lista fixa de todos os modelos que existem.service_tierscomo um filtro (plural, tipo lista) restringe a níveis específicos;group_by=["service_tier"]em vez disso detalha cada nível que você usou.data_residencyreflete onde uma solicitação foi processada, o que pode importar independentemente de onde sua organização ou seus clientes estão localizados.- Todas as três dimensões se compõem umas com as outras e com os filtros de chave de API e workspace abordados em Consultando Uso por Chave de API e Workspace com a Admin API, então você pode, por exemplo, agrupar por modelo e região em uma única chamada.
Dimensões em Destaque
| Dimensão | Uso Principal | Valores Típicos que Você Verá |
|---|---|---|
model | Análise de mix de custo e capacidade | Identificadores de modelo como os de Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5, Claude Haiku 4.5 |
service_tier | Análise de trade-off de custo e latência | Níveis como standard, priority e batch |
data_residency | Conformidade e verificação de tratamento de dados | Identificadores de região refletindo onde o processamento ocorreu |
Notas de Python
# Combine o agrupamento de modelo e região em uma única chamada quando precisar responder
# "qual modelo rodou em qual região", não apenas cada dimensão independentemente.
report = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
group_by=["model", "data_residency"],
)
for bucket in report.data:
print(bucket.model, bucket.data_residency, bucket.output_tokens)Parâmetros e Valores de Retorno
| Parâmetro | Tipo | Descrição |
|---|---|---|
group_by | list[str] | Aceita "model", "service_tier", "data_residency" juntamente com "api_key_id" e "workspace_id". |
service_tiers | list[str] | Filtra para valores específicos de nível de serviço. |
models | list[str] | Filtra para identificadores de modelo específicos. |
starting_at / ending_at | str (ISO 8601) | Janela de tempo do relatório. |
Armadilhas
- Assumir que os identificadores de modelo são nomes estáveis e legíveis por humanos. A API relata o identificador exato do modelo usado no momento da solicitação, que pode não corresponder ao nome de marketing que você esperaria. Correção: mapeie identificadores para rótulos legíveis por humanos em seu próprio código antes de apresentar um relatório a um público não técnico.
- Comparar o gasto por nível sem também verificar o volume. Um nível mostrando custo total menor pode simplesmente ter menos tráfego, não um preço melhor. Correção: calcule uma taxa por token ou por solicitação, não apenas um total bruto, ao comparar níveis.
- Tratar "residência de dados" como a mesma coisa que "onde minha organização está baseada". Eles são não relacionados; residência reflete onde a solicitação foi processada. Correção: leia o campo
data_residencyreal em vez de assumir que ele corresponde ao endereço de faturamento da sua conta. - Esquecer que uma renomeação ou aposentadoria de modelo altera a chave de agrupamento daqui para frente. Relatórios históricos mantêm o identificador antigo, o novo uso usa o novo, então uma comparação ingênua mês a mês pode parecer que um modelo "desapareceu". Correção: normalize os identificadores em sua própria camada de mapeamento e anote as datas de aposentadoria ao comparar em um limite.
- Filtrar por nível de serviço quando você quis dizer filtrar por modelo, ou vice-versa. Estes são parâmetros separados com valores aceitos separados. Correção: verifique novamente a qual dimensão um determinado identificador pertence antes de construir a lista de filtros, especialmente quando ambos vêm da mesma configuração upstream.
- Construir um relatório de conformidade a partir de um total único não agrupado. Um total plano não diz nada sobre quais regiões estiveram envolvidas. Correção: sempre agrupe explicitamente por
data_residencyquando o propósito do relatório for uma atestação de residência.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Agrupar por modelo / nível / região via Admin API | Você precisa de um detalhamento recorrente, scriptável ou exportável | Uma única verificação manual é suficiente |
| Páginas de Uso e Custo do Console, filtradas por modelo ou nível na UI | Uma visualização rápida única, sem necessidade de código | Você precisa disso combinado com dados de residência, juntado com outros sistemas, ou executado em uma programação |
| Contate sua equipe de conta para uma atestação formal de residência | Você precisa de uma declaração de conformidade legalmente vinculativa, não apenas dados observados | Você só precisa de visibilidade de engenharia sobre onde o tráfego está chegando |
FAQs
Qual é a diferença entre filtrar por service_tiers e agrupar por service_tier?
service_tiers=[...]restringe o relatório apenas aos níveis que você lista.group_by=["service_tier"]mantém todos os níveis no escopo e retorna uma linha por nível.- Use o filtro quando você já sabe qual nível está investigando; use o agrupamento para comparar níveis lado a lado.
Por que o gasto difere entre modelos além de apenas seu preço por token?
Um modelo mais capaz também pode produzir saídas mais longas e completas para o mesmo prompt, ou exigir menos retentativas para obter uma resposta utilizável, ambos alterando o volume de tokens independentemente da taxa por token. Comparar modelos pelo custo total, não apenas pelo preço por token, captura isso.
O que é um nível de serviço, concretamente?
Reflete como uma solicitação foi roteada para processamento, por exemplo, processamento padrão em tempo real versus uma fila batch que troca latência por um preço menor. Cada nível é cobrado de forma diferente, razão pela qual é exposto como sua própria dimensão filtrável e agrupável.
Posso filtrar para ver apenas solicitações processadas em uma região específica?
report = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
data_residency=["eu"],
)O agrupamento por modelo me diz sobre diferenças de qualidade ou capacidade, não apenas custo?
Não, o relatório de uso apenas relata contagens de tokens e custos derivados, não métricas de qualidade ou capacidade. Ele pode mostrar que uma carga de trabalho mudou de um modelo para outro e como isso alterou os gastos, mas avaliar se essa mudança foi uma boa troca requer suas próprias métricas de qualidade ao lado desses dados.
Por que uma equipe de conformidade se importaria especificamente com a dimensão data_residency?
- Alguns contratos ou regulamentos exigem saber, e às vezes restringir, onde os dados de solicitação são processados.
- Um relatório de residência permite que uma equipe de conformidade verifique o comportamento real em vez de confiar apenas na configuração.
- É uma evidência útil durante uma auditoria ou uma revisão de due diligence de cliente.
Posso combinar o agrupamento de modelo, nível e região em uma única solicitação?
Sim, group_by aceita uma lista, então group_by=["model", "service_tier", "data_residency"] retorna uma linha por combinação única de todos os três. Esteja ciente de que combinar várias dimensões de alta cardinalidade pode produzir um grande número de linhas.
Como sei quais identificadores de modelo são atualmente válidos para filtrar?
A fonte mais segura é o seu próprio relatório de uso recente e não agrupado: agrupe por model em uma janela recente e leia os identificadores que realmente aparecem, em vez de codificar uma lista que pode ficar desatualizada à medida que modelos são lançados ou aposentados.
Nível de serviço é a mesma coisa que limites de taxa ou acesso prioritário?
Eles estão relacionados, mas são distintos. O nível de serviço determina como uma solicitação é processada e precificada; limites de taxa e acesso prioritário governam quanto tráfego você pode enviar e como ele é enfileirado sob carga. Um relatório de uso reflete o nível que uma solicitação realmente usou, não os limites configurados da sua conta.
O que acontece se eu agrupar por data_residency, mas minha organização usa apenas uma região?
O relatório simplesmente retorna uma única linha para essa região, o que é um resultado normal e esperado. Ainda é útil como uma confirmação positiva para um relatório de conformidade, mostrando que todo o tráfego processado permaneceu dentro da região esperada.
Relatórios de modelo, nível e residência devem ser executados juntos ou separadamente?
Ambos funcionam; depende do público. Um relatório combinado com todos os três agrupados responde a perguntas precisas interligadas, mas produz mais linhas, enquanto relatórios separados de dimensão única (como mostrado no exemplo de trabalho) são mais fáceis de ler individualmente e geralmente são o que uma revisão mensal realmente precisa.
Relacionados
- Como a Admin API de Uso e Custo Modela Seu Gasto - o modelo de bucket de tokens que cada uma dessas dimensões detalha.
- Consultando Uso por Chave de API e Workspace com a Admin API - as dimensões de identidade com as quais esses filtros se compõem.
- Construindo um Painel de Custo a partir de Detalhamentos de Tokens Não Cacheado, Cacheado e de Saída - incorpore o agrupamento de modelo e nível em um pipeline de custo completo.
- API de Análise Empresarial: Atribuição de Custo por Usuário entre Chat e Código Claude - uma API relacionada para atribuir custo a usuários individuais, não apenas a modelo ou nível.
- Comparação: Admin API vs. Páginas de Uso e Custo do Console - decida se os filtros integrados do Console são suficientes para essas dimensões.
Versões da Stack: Escrito contra a 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.