Filtrado de uso por modelo, nivel de servicio y residencia de datos
Segmenta los datos de uso por versión de modelo, nivel de servicio y residencia de datos para informes de cumplimiento.
Resumen
Las preguntas sobre costos y cumplimiento no se detienen en "¿quién gastó esto?".
A menudo continúan con "¿qué modelo?", "¿bajo qué nivel de procesamiento?" y "¿en qué región se manejaron estos datos?".
La API de administración expone las tres como dimensiones de filtro y agrupación, junto con los filtros de clave de API y espacio de trabajo cubiertos en otras partes de esta sección.
El modelo y el nivel de servicio son principalmente preguntas de costos: diferentes modelos y niveles tienen precios por token diferentes.
La residencia de datos es principalmente una pregunta de cumplimiento: algunas organizaciones están obligadas contractual o legalmente a saber, y a veces a restringir, dónde se procesaron los datos de sus solicitudes.
Receta
import anthropic
client = anthropic.Anthropic()
# Agrupa el uso por modelo, para que puedas ver el gasto por modelo uno al lado del otro
by_model = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
group_by=["model"],
)
# Filtra a un único nivel de servicio
by_tier = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
service_tiers=["batch"],
)
# Agrupa por región de residencia de datos para una exportación de cumplimiento
by_region = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
group_by=["data_residency"],
)Cuándo usar esto:
- Quieres ver si un mes costoso se debió a la mezcla de modelos (más Opus, menos Haiku) en lugar del volumen bruto de solicitudes.
- Estás decidiendo si el nivel de servicio batch o priority vale la diferencia de precio para una carga de trabajo determinada.
- El departamento legal o de cumplimiento necesita un informe de qué regiones procesaron los datos de solicitud de tu organización durante un período determinado.
- Estás validando que un compromiso de residencia de datos hecho a un cliente se está cumpliendo en la práctica.
Ejemplo de trabajo
"""
model_tier_region_report.py
Produce tres desgloses uno al lado del otro para una revisión mensual: gasto por
modelo, gasto por nivel de servicio y volumen de solicitudes por región de residencia de datos,
útil para un resumen mensual combinado de costos y cumplimiento.
"""
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 nivel de servicio:")
for tier, tokens in spend_by_service_tier():
print(f" {tier:<30}{tokens:>15,} tokens")
print("\nPor región de residencia de datos:")
for region, tokens in volume_by_residency():
print(f" {region:<30}{tokens:>15,} tokens")Lo que esto demuestra:
- Cada función agrupa por una sola dimensión, lo que mantiene la salida de cada función legible y útil de forma independiente.
total_tokenssuma los cuatro tipos de tokens solo para la clave de ordenación, mientras que el informe subyacente aún conserva el desglose por tipo si lo necesitas más adelante.- Los tres informes pueden ejecutarse de forma independiente o combinarse en un único resumen mensual que cubra tanto un ángulo de costos como uno de cumplimiento.
- La ordenación descendente muestra primero los mayores impulsores de costos o volumen, que suele ser lo que un revisor quiere ver en la parte superior.
Inmersión profunda
Cómo funciona
group_by=["model"]devuelve una fila por cada cadena de modelo distinta que tu organización utilizó realmente en la ventana, no una lista fija de todos los modelos que existen.service_tierscomo filtro (plural, tipo lista) limita a niveles específicos;group_by=["service_tier"]en cambio desglosa cada nivel que utilizaste.data_residencyrefleja dónde se procesó una solicitud, lo que puede ser importante independientemente de dónde se encuentre tu organización o sus clientes.- Las tres dimensiones se componen entre sí y con los filtros de clave de API y espacio de trabajo cubiertos en Consultar uso por clave de API y espacio de trabajo con la API de administración, por lo que puedes, por ejemplo, agrupar por modelo y región en una sola llamada.
Dimensiones de un vistazo
| Dimensión | Uso principal | Valores típicos que verás |
|---|---|---|
model | Análisis de mezcla de costos y capacidades | Identificadores de modelo como los de Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5, Claude Haiku 4.5 |
service_tier | Análisis de compensación de costos y latencia | Niveles como standard, priority y batch |
data_residency | Verificación de cumplimiento y manejo de datos | Identificadores de región que reflejan dónde ocurrió el procesamiento |
Notas de Python
# Combina la agrupación de modelos y regiones en una sola llamada cuando necesites responder
# "qué modelo se ejecutó en qué región", no solo cada dimensión de forma independiente.
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 y valores de retorno
| Parámetro | Tipo | Descripción |
|---|---|---|
group_by | list[str] | Acepta "model", "service_tier", "data_residency" junto con "api_key_id" y "workspace_id". |
service_tiers | list[str] | Filtra a valores específicos de nivel de servicio. |
models | list[str] | Filtra a identificadores de modelo específicos. |
starting_at / ending_at | str (ISO 8601) | Ventana de tiempo del informe. |
Trampas comunes
- Asumir que los identificadores de modelo son nombres estables y legibles por humanos. La API informa el identificador exacto del modelo utilizado en el momento de la solicitud, que puede no coincidir con el nombre de marketing que esperarías. Solución: mapea los identificadores a etiquetas legibles por humanos en tu propio código antes de presentar un informe a una audiencia no técnica.
- Comparar el gasto por nivel sin verificar también el volumen. Un nivel que muestra un costo total menor podría tener simplemente menos tráfico, no un mejor precio. Solución: calcula una tarifa por token o por solicitud, no solo un total bruto, al comparar niveles.
- Tratar la "residencia de datos" como lo mismo que "dónde se basa mi organización". No están relacionados; la residencia refleja dónde se procesó la solicitud. Solución: lee el campo
data_residencyreal en lugar de asumir que coincide con la dirección de facturación de tu cuenta. - Olvidar que un cambio de nombre o retiro de modelo cambia la clave de agrupación en el futuro. Los informes históricos conservan el identificador antiguo, el uso nuevo utiliza el nuevo, por lo que una comparación ingenua mes a mes puede parecer que un modelo "desapareció". Solución: normaliza los identificadores en tu propia capa de mapeo y anota las fechas de retiro al comparar a través de un límite.
- Filtrar por nivel de servicio cuando querías filtrar por modelo, o viceversa. Estos son parámetros separados con valores aceptados separados. Solución: verifica dos veces a qué dimensión pertenece un identificador dado antes de construir la lista de filtros, especialmente cuando ambos provienen de la misma configuración upstream.
- Construir un informe de cumplimiento a partir de un total único y sin agrupar. Un total plano no te dice nada sobre qué regiones estuvieron involucradas. Solución: agrupa siempre explícitamente por
data_residencycuando el propósito del informe sea una certificación de residencia.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Agrupar por modelo / nivel / región a través de la API de administración | Necesitas un desglose recurrente, programable o exportable | Una única verificación manual es suficiente |
| Páginas de Uso y Costos de la Consola, filtradas por modelo o nivel en la UI | Una mirada rápida y única, sin necesidad de código | Necesitas esto combinado con datos de residencia, unido con otros sistemas, o ejecutado en un horario |
| Contactar a tu equipo de cuentas para una certificación formal de residencia | Necesitas una declaración de cumplimiento legalmente vinculante, no solo datos observados | Solo necesitas visibilidad de ingeniería sobre dónde está aterrizando el tráfico |
Preguntas frecuentes
¿Cuál es la diferencia entre filtrar por service_tiers y agrupar por service_tier?
service_tiers=[...]restringe el informe solo a los niveles que enumeras.group_by=["service_tier"]mantiene todos los niveles en el ámbito y devuelve una fila por nivel.- Usa el filtro cuando ya sepas qué nivel estás investigando; usa la agrupación para comparar niveles uno al lado del otro.
¿Por qué el gasto podría diferir entre modelos más allá de su precio por token?
Un modelo más capaz también puede producir resultados más largos y completos para la misma indicación, o requerir menos reintentos para obtener una respuesta utilizable, ambos cambian el volumen de tokens independientemente de la tarifa por token. Comparar modelos en el costo total, no solo en el precio por token, captura eso.
¿Qué es concretamente un nivel de servicio?
Refleja cómo se enrutó una solicitud para su procesamiento, por ejemplo, procesamiento estándar en tiempo real frente a una cola batch que intercambia latencia por un precio más bajo. Cada nivel se factura de manera diferente, por lo que se expone como su propia dimensión filtrable y agrupable.
¿Puedo filtrar para ver solo las solicitudes procesadas en una región específica?
report = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
data_residency=["eu"],
)¿Agrupar por modelo me dice sobre diferencias de calidad o capacidad, no solo sobre costos?
No, el informe de uso solo informa recuentos de tokens y costos derivados, no métricas de calidad o capacidad. Puede mostrarte que una carga de trabajo cambió de un modelo a otro y cómo eso cambió el gasto, pero evaluar si ese cambio fue un buen intercambio requiere tus propias métricas de calidad junto con estos datos.
¿Por qué un equipo de cumplimiento podría preocuparse específicamente por la dimensión data_residency?
- Algunos contratos o regulaciones requieren saber, y a veces restringir, dónde se procesan los datos de las solicitudes.
- Un informe de residencia permite a un equipo de cumplimiento verificar el comportamiento real en lugar de depender solo de la configuración.
- Es evidencia útil durante una auditoría o una revisión de diligencia debida de un cliente.
¿Puedo combinar la agrupación de modelos, niveles y regiones en una sola solicitud?
Sí, group_by acepta una lista, por lo que group_by=["model", "service_tier", "data_residency"] devuelve una fila por cada combinación única de los tres. Ten en cuenta que combinar varias dimensiones de alta cardinalidad puede producir un gran número de filas.
¿Cómo sé qué identificadores de modelo son válidos actualmente para filtrar?
La fuente más segura es tu propio informe de uso reciente y sin agrupar: agrupa por model durante una ventana reciente y lee los identificadores que realmente aparecen, en lugar de codificar una lista que puede desactualizarse a medida que se lanzan o retiran modelos.
¿Es el nivel de servicio lo mismo que los límites de tasa o el acceso prioritario?
Están relacionados pero son distintos. El nivel de servicio determina cómo se procesa y se factura una solicitud; los límites de tasa y el acceso prioritario rigen cuántas solicitudes puedes enviar y cómo se ponen en cola bajo carga. Un informe de uso refleja el nivel que una solicitud utilizó realmente, no los límites configurados de tu cuenta.
¿Qué sucede si agrupo por data_residency pero mi organización solo usa una región?
El informe simplemente devuelve una sola fila para esa región, lo cual es un resultado normal y esperado. Sigue siendo útil como confirmación positiva para un informe de cumplimiento, mostrando que todo el tráfico procesado se mantuvo dentro de la región esperada.
¿Deberían ejecutarse los informes de modelo, nivel y residencia juntos o por separado?
Cualquiera de las dos funciona; depende de la audiencia. Un informe combinado con los tres agrupados responde a preguntas precisas transversales pero produce más filas, mientras que los informes separados de una sola dimensión (como se muestra en el ejemplo de trabajo) son más fáciles de leer individualmente y suelen ser lo que una revisión mensual realmente necesita.
Relacionados
- Cómo la API de administración de uso y costos modela tu gasto - el modelo de bucket de tokens en el que finalmente se desglosa cada una de estas dimensiones.
- Consultar uso por clave de API y espacio de trabajo con la API de administración - las dimensiones de identidad con las que se componen estos filtros.
- Creación de un panel de costos a partir de desgloses de tokens sin caché, con caché y de salida - integra la agrupación de modelos y niveles en un pipeline de costos completo.
- API de análisis empresarial: Atribución de costos por usuario en chat y código Claude - una API relacionada para atribuir costos a usuarios individuales, no solo a modelos o niveles.
- Comparación: Páginas de Uso y Costos de la API de Administración vs. Consola - decide si los filtros integrados de la Consola son suficientes para estas dimensiones.
Versiones de pila: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de modelos, precios y versiones del SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.