Consultar el uso por clave de API y espacio de trabajo con la API de administración
Filtra los datos históricos de uso y costos hasta una clave de API o espacio de trabajo individual.
Resumen
La mayoría de las preguntas sobre costos no son "¿cuánto gastamos en total?", sino "¿cuánto gastó este equipo?".
La API de administración responde a eso permitiéndote filtrar y agrupar informes de uso y costos por api_key_id y workspace_id.
El filtrado reduce el conjunto de resultados a uno o unos pocos identificadores antes de que la API calcule el informe.
La agrupación mantiene las filas de cada identificador visibles una al lado de la otra, lo que suele ser la mejor opción una vez que tienes más de una clave o espacio de trabajo para comparar.
Esta página cubre ambos, además de cómo resolver un nombre de clave o espacio de trabajo legible por humanos en el ID que espera la API.
Receta
import anthropic
client = anthropic.Anthropic() # lee ANTHROPIC_ADMIN_KEY del entorno
# Filtrar: uso para una clave 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 un espacio de trabajo específico
by_workspace = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
workspace_ids=["wksp_01abc123"],
)
# Agrupar: uso desglosado por clave, sin filtro aplicado
grouped = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
group_by=["api_key_id"],
)Cuándo usar esto:
- Estás investigando un pico de costos y sospechas que se remonta a una integración.
- Necesitas un número por clave o por espacio de trabajo para un informe de reparto de gastos o presupuesto.
- Estás auditando qué claves siguen activas antes de revocar las que no se usan.
- Quieres una tabla de clasificación de los principales gastos en tu organización, no un total único.
Ejemplo de trabajo
import anthropic
from datetime import datetime, timedelta, timezone
client = anthropic.Anthropic()
def usage_for_key(api_key_id: str, days: int = 30) -> dict:
"""Devuelve el uso total de tokens para una clave de API durante los últimos N días."""
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]]:
"""Clasifica los espacios de trabajo por volumen de tokens de salida durante los últimos N días."""
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)Lo que esto demuestra:
usage_for_keymuestra un filtro de identificador único utilizado para responder "¿cuánto costó esta clave?".top_workspaces_by_outputmuestra la agrupación utilizada para clasificar muchos identificadores a la vez, sin filtrar ninguno de ellos.- Ambas funciones acumulan totales de tipos de tokens por separado en lugar de colapsarlos, para que el llamador aún pueda aplicar precios por tipo más tarde.
bucket_width="1d"evita que el informe devuelva una única fila sumada gigante cuando podría desear una tendencia más adelante.
Inmersión profunda
Cómo funciona
api_key_idsyworkspace_idsson ambos filtros de tipo lista; pasar varios valores devuelve el uso de cualquiera de ellos, no solo del primero.- El filtrado ocurre antes de la agregación, por lo que un informe filtrado es más barato de razonar y típicamente más rápido que obtener todo y filtrar en el lado del cliente.
group_byy los parámetros de filtro se componen: puedes filtrar a un puñado de espacios de trabajo y aún así agrupar el resultado por clave de API dentro de ellos.- Los IDs, no los nombres, son lo que la API acepta. Un espacio de trabajo llamado "Growth Team" y un ID de espacio de trabajo como
wksp_01abc123son cosas diferentes, y solo el ID es un valor de filtro válido.
Resolución de nombres a IDs
| Tienes | Necesitas | Cómo obtenerlo |
|---|---|---|
| Un nombre de espacio de trabajo mostrado en la Consola | workspace_id | Enumera los espacios de trabajo a través del endpoint de espacios de trabajo de la API de administración, o copia el ID desde la página de configuración del espacio de trabajo en la Consola |
| La etiqueta de visualización de una clave | api_key_id | Enumera las claves de API a través del endpoint de claves de API de la API de administración; la etiqueta y el ID se devuelven juntos |
| Solo un total de costos parcial de la interfaz de usuario de la Consola | Ambos | Realiza una referencia cruzada con la página de uso de la Consola, que muestra tanto el nombre como el ID al hacer clic en un espacio de trabajo o clave |
import anthropic
client = anthropic.Anthropic()
# Resuelve el nombre legible por humanos de un espacio de trabajo al ID que espera la API de uso
workspaces = client.beta.admin.workspaces.list()
target = next(w for w in workspaces.data if w.name == "Growth Team")
print(target.id) # usa este valor como filtro de workspace_idsNotas de Python
# Construir una lista de filtros dinámicamente es un patrón común una vez que los IDs de clave
# provienen de tu propia base de datos en lugar de estar 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 "sin filtro" para el SDK
)Parámetros y valores de retorno
| Parámetro | Tipo | Descripción |
|---|---|---|
api_key_ids | list[str] | Restringe el informe a uno o más IDs de clave de API. |
workspace_ids | list[str] | Restringe el informe a uno o más IDs de espacio de trabajo. |
group_by | list[str] | Devuelve una fila por cada combinación única de estas dimensiones, por ejemplo, ["api_key_id"]. |
starting_at | str (ISO 8601) | Inicio de la ventana del informe, requerido. |
ending_at | str (ISO 8601) | Fin de la ventana del informe, opcional, por defecto es ahora. |
Errores comunes
- Pasar una etiqueta de clave en lugar de un ID.
api_key_idssolo acepta el ID de la clave, no su nombre de visualización. Solución: enumera primero las claves de API y lee el campoid, o almacena el ID junto con la etiqueta en tu propio sistema. - Filtrar y agrupar por el mismo campo y esperar un resultado filtrado y no agrupado. Si filtras a un espacio de trabajo y también agrupas por
workspace_id, obtendrás un resultado agrupado de una sola fila, lo cual es inofensivo pero redundante. Solución: agrupa solo por un campo cuando tengas más de un valor de él en el ámbito. - Asumir que un resultado vacío significa que la clave nunca existió. Un informe vacío a menudo significa que la clave tuvo cero uso en esa ventana. Solución: verifica la existencia de la clave por separado a través del endpoint de claves de la API de administración antes de concluir que no es válida.
- Olvidar que una clave eliminada o rotada todavía tiene uso histórico. Los datos de uso persisten después de que una clave es revocada. Solución: mantén un mapeo local del ID de clave a la etiqueta incluso después de la rotación, para que los informes antiguos sigan siendo legibles.
- Construir una lista enorme de
api_key_idspara solucionar la falta de un filtro "no en el espacio de trabajo X". La API filtra por inclusión, no por exclusión. Solución: obtén todas las claves de la organización, resta las que deseas excluir en Python, y luego pasa el resto como filtro. - Volver a ejecutar un informe por clave en un bucle, una vez por clave. Esto multiplica las llamadas a la API innecesariamente. Solución: usa
group_by=["api_key_id"]en una sola llamada en lugar de N llamadas filtradas separadas.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
Filtrar por api_key_ids / workspace_ids | Ya sabes exactamente qué clave o espacio de trabajo te interesa | Necesitas comparar más de un puñado de identificadores, ya que la agrupación escala mejor |
Agrupar por api_key_id / workspace_id | Quieres el uso de cada identificador visible a la vez, por ejemplo, una tabla de clasificación | Solo te interesa un identificador específico y quieres la respuesta más pequeña posible |
| Páginas de Uso y Costos de la Consola, filtradas en la interfaz | Una búsqueda manual única, no se necesita código | Necesitas esto en un horario recurrente o unido a otros datos de negocio |
Preguntas frecuentes
¿Cuál es la diferencia entre filtrar por workspace_ids y agrupar por workspace_id?
- Filtrar (
workspace_ids=[...]) restringe el informe solo a los espacios de trabajo que enumeras, devolviendo menos filas. - Agrupar (
group_by=["workspace_id"]) mantiene todos los espacios de trabajo en el ámbito pero divide el resultado en una fila por espacio de trabajo. - Usa el filtrado cuando sepas exactamente a quién buscas; usa la agrupación cuando quieras comparar muchos.
¿Puedo filtrar por api_key_ids y workspace_ids en la misma solicitud?
Sí. Ambos filtros se pueden aplicar juntos, y la API devuelve el uso que coincide con ambas condiciones. Esto es útil para reducir a una clave específica que pertenece a un espacio de trabajo específico cuando los IDs de clave por sí solos no son lo suficientemente únicos para tu caso de uso.
¿Cómo encuentro el ID de una clave de API si solo conozco su etiqueta en la Consola?
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)¿El filtrado por clave de API también filtra los datos de costos, o solo los datos de uso?
Ambos. Los mismos filtros api_key_ids y workspace_ids se aplican al endpoint del informe de costos, así como al endpoint del informe de uso, ya que el costo se deriva de los mismos registros subyacentes.
¿Qué sucede si paso un ID de clave de API que no existe?
La llamada al informe tiene éxito pero no devuelve datos para ese ID, en lugar de generar un error. Esto vale la pena manejarlo explícitamente si estás creando automatización que debería alertar sobre un ID de clave faltante o mal escrito.
¿Puedo consultar el uso de una clave que ya ha sido revocada?
Sí. Los registros de uso históricos están vinculados al ID de la clave y persisten independientemente de si la clave todavía está activa, por lo que las claves revocadas siguen siendo consultables durante el tiempo que cubra la ventana de retención de datos de tu organización.
¿Hay un límite en la cantidad de IDs de clave de API que puedo pasar en un filtro?
La lista acepta múltiples IDs, pero listas muy grandes se manejan mejor con la agrupación en lugar de una lista de filtros enorme. Si estás filtrando más de unas pocas docenas de claves, cambia a group_by=["api_key_id"] y filtra posteriormente en Python.
¿Cómo combino un filtro de espacio de trabajo con un desglose por modelo?
report = client.beta.usage.report(
starting_at="2026-06-01T00:00:00Z",
workspace_ids=["wksp_01abc123"],
group_by=["model"],
)Esto filtra a un espacio de trabajo, luego agrupa las filas restantes por modelo.
¿Por qué agruparía por api_key_id en lugar de simplemente obtener el uso de cada clave por separado?
Una sola llamada agrupada es un viaje de ida y vuelta de red y una consulta contra los datos subyacentes, en lugar de N llamadas para N claves. También garantiza que los datos de cada clave provengan de la misma ventana de tiempo exacta, lo que es importante cuando estás creando un informe que necesita sumar correctamente.
¿Los IDs de espacio de trabajo y los IDs de clave de API usan el mismo formato?
No, usan prefijos distintos (por ejemplo, los IDs de espacio de trabajo comúnmente comienzan con wksp_ y los IDs de clave de API con apikey_), lo que facilita la detección de un valor de filtro mezclado de un vistazo durante la revisión del código.
¿Puedo filtrar por un equipo o departamento en lugar de un espacio de trabajo o clave?
No directamente, la API solo entiende el ID de clave de API y el ID de espacio de trabajo como filtros de identidad. Si tu organización mapea equipos a espacios de trabajo o a un conjunto de claves, creas ese mapeo tú mismo y lo aplicas en tu propio código después de obtener el informe agrupado.
¿Debería filtrar en el servidor con los parámetros de la API, o obtener todo y filtrar en Python?
Filtra en el servidor con api_key_ids o workspace_ids siempre que conozcas el objetivo con anticipación. Reduce la cantidad de datos transferidos y la cantidad de agregación que la API tiene que hacer, y mantiene tu código Python más simple ya que no está reimplementando la lógica de filtrado que la API ya proporciona.
Relacionados
- Cómo la API de administración de uso y costos modela tus gastos - el modelo de cubo de tokens en el que se dividen estos filtros.
- Conceptos básicos de seguimiento de uso y costos - el informe sin filtrar en el que se basa esta página.
- Creación de un panel de costos a partir de desgloses de tokens no cacheados, cacheados y de salida - convierte un informe filtrado o agrupado en un panel.
- Filtrado de uso por modelo, nivel de servicio y residencia de datos - las otras dimensiones sobre las que puedes segmentar además de la clave y el espacio de trabajo.
- Plantilla ADR: Un modelo de reparto de gastos para el uso de claves de API multi-equipo - cómo el filtrado por clave alimenta una política real de reparto de gastos.
Versiones de Stack: Escrito contra la línea de modelos de 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.