Cómo la API de Administración de Uso y Costos Modela tus Gastos
Cada solicitud que envías a Claude produce más de un número que vale la pena rastrear.
Está la entrada que escribiste, el contexto que reutilizaste de la caché y la salida que Claude generó, y cada uno de ellos tiene un precio diferente.
La API de Administración de Uso y Costos se basa en esa realidad: no te entrega una única cifra de "costo" por solicitud.
En cambio, te entrega un desglose estructurado, agrupado por tipo de token y organizado por dimensiones como clave de API, espacio de trabajo y modelo, que puedes volver a ensamblar en el informe que realmente necesitas.
Comprender ese modelo de cubos, antes de escribir una sola consulta, es lo que hace que el resto de la API sea predecible en lugar de confuso.
Resumen
- Idea Central: La API de Administración reporta el uso como cubos de tipo de token separados (entrada no cacheada, entrada cacheada, creación de caché, salida) en lugar de un único número de costo combinado.
- Por Qué Importa: Cada cubo tiene un precio por token diferente, por lo que colapsarlos prematuramente oculta de dónde provienen realmente tus gastos.
- Conceptos Clave: cubos de tokens, dimensiones de agrupación, uso vs. costo, nivel de servicio, granularidad temporal.
- Cuándo Usar: Utiliza este modelo siempre que necesites explicar, auditar o pronosticar gastos en lugar de simplemente echar un vistazo a un total.
- Limitaciones / Compensaciones: La API te proporciona las materias primas para un informe de costos, no uno terminado; aún debes aplicar tus propios precios y construir tu propia agregación.
- Temas Relacionados: precios conscientes de la caché, atribución por clave, modelado de reparto de gastos (chargeback), paneles de la Consola.
Fundamentos
En su núcleo, la API de Administración trata cada solicitud como una pequeña transacción con hasta cuatro líneas de detalle.
Tokens de entrada no cacheados son los tokens de prompt que Claude tuvo que procesar frescos, sin un golpe de caché previo.
Tokens de entrada cacheados son tokens de prompt servidos desde una caché previamente escrita, facturados con un gran descuento en comparación con los tokens no cacheados.
Tokens de creación de caché son los tokens que pagaste una prima para escribir en la caché en primer lugar, para que una solicitud posterior pudiera leerlos de forma económica.
Tokens de salida son lo que Claude generó en respuesta, y se facturan al precio más alto de los cuatro, ya que la generación es la parte más intensiva en cómputo de una solicitud.
Una analogía simple: piensa en un recibo de restaurante que detalla el aperitivo, el plato principal y el postre en lugar de imprimir un total único.
Podrías pedir solo el total, pero la versión detallada es lo que te permite detectar que el postre, no el plato principal, es donde la factura aumentó.
La API de Administración está diseñada para entregarte ese recibo detallado para cada solicitud en toda tu organización, no solo para una comida.
Cada registro de uso de la API contiene estos cuatro recuentos de tokens, además de metadatos que describen a qué clave de API, espacio de trabajo, modelo y nivel de servicio pertenece la solicitud.
Esa metadata es lo que convierte una pila de recibos en algo que un equipo de finanzas, o un ingeniero que investiga un pico de costos, puede consultar.
Mecánicas e Interacciones
El modelo mental de la API tiene dos mitades distintas: uso y costo.
Uso es un recuento, el número bruto de tokens de cada tipo consumido en una ventana de tiempo dada, segmentado según las dimensiones de agrupación que elijas.
Costo es el uso multiplicado por el precio, expresado en dólares, y reportado con la misma granularidad que el uso para que puedas rastrear una cifra en dólares hasta los tokens que la produjeron.
Esta separación es importante porque los precios pueden cambiar con el tiempo, y una consulta de uso puro te permite reevaluar datos históricos con una nueva tabla de tarifas sin tener que volver a obtener nada.
import anthropic
client = anthropic.Anthropic()
# El uso se agrupa por tipo de token y se organiza por las dimensiones que elijas
report = client.beta.usage.cost_report(
starting_at="2026-06-01T00:00:00Z",
group_by=["workspace_id", "model"],
)Las dimensiones de agrupación actúan como una cláusula GROUP BY en SQL: eliges en qué columnas segmentar, y la API devuelve una fila por cada combinación única.
Agrupa por api_key_id y obtienes el gasto por clave, útil para el reparto de gastos (chargeback).
Agrupa por model y ves si una elección de modelo costosa, no el volumen de solicitudes, está impulsando la factura.
Agrupa por service_tier y puedes separar el tráfico de nivel estándar del tráfico de nivel de lote o prioritario, que tienen diferentes puntos de precio.
La granularidad temporal también interactúa con la agrupación: un cubo diario por espacio de trabajo cuenta una historia muy diferente a un cubo por hora por clave de API, y la API te permite elegir ambos de forma independiente.
Un error de razonamiento común es tratar el "uso" y el "costo" como si siempre estuvieran sincronizados.
Generalmente lo están, pero no siempre, ya que un cambio de precio, un crédito promocional o un descuento de nivel de servicio pueden alterar la cifra en dólares sin alterar los recuentos de tokens, y la separación de estos dos conceptos por parte de la API es precisamente lo que te permite notarlo.
Consideraciones y Aplicaciones Avanzadas
A escala, el modelo de cubos de tokens se convierte en la base de dos cosas que toda organización de ingeniería necesita eventualmente: atribución y pronóstico.
Atribución significa responder "¿quién gastó esto?", lo que requiere agrupar por clave de API o espacio de trabajo y consolidarlo a un equipo o producto.
Pronóstico significa responder "¿cuánto costará el próximo mes?", lo que requiere suficiente granularidad histórica para modelar tendencias por tipo de token, ya que la adopción de caché, la mezcla de modelos y la longitud del prompt se mueven de forma independiente.
El modelo de cubos también tiene un ángulo directo de seguridad y gobernanza: dado que los tokens de creación de caché y de lectura de caché son visibles por separado, puedes detectar un espacio de trabajo que paga repetidamente para reescribir una caché que nunca vuelve a leer, lo que generalmente es una señal de una clave de caché mal configurada en lugar de una elección deliberada.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Consultar la API de Administración directamente | Granularidad histórica completa, programable, agrupable por cualquier dimensión | Requiere que construyas tu propio almacenamiento y visualización | Informes automatizados recurrentes, pipelines de reparto de gastos (chargeback) |
| Usar las páginas de Uso y Costos de la Consola | No requiere código, rápido para preguntas ad hoc | No automatizable, limitado a los segmentos integrados de la UI | Investigaciones únicas, comprobaciones rápidas |
| Almacenar en caché la respuesta de la API en tu propio almacén de datos | Permite uniones con datos de productos o clientes, análisis de tendencias históricas | Eres responsable de la frescura y corrección de la caché | Paneles financieros a largo plazo |
A medida que las organizaciones maduran más allá de una única clave de API, el modelo de cubos escala naturalmente a un modelo de reparto de gastos (chargeback), donde los mismos datos de uso y costo por clave responden a "¿cuánto gastamos" y también a "¿qué presupuesto de qué equipo se ve afectado?".
Esa es una decisión de gobernanza superpuesta a los mismos datos brutos, no una API diferente.
Conceptos Erróneos Comunes
- "El costo es solo uso por un precio único." En realidad, cada tipo de token tiene su propio precio, por lo que la misma solicitud puede tener cuatro tasas diferentes por token integradas en una sola factura.
- "Los tokens cacheados son gratis." Tienen un gran descuento, no son gratis, y los tokens de creación de caché tienen en realidad una prima sobre los tokens de entrada estándar.
- "La API de Administración y la Consola muestran números diferentes." Leen de los mismos registros de uso subyacentes; cualquier discrepancia aparente generalmente proviene de diferentes ventanas de tiempo o opciones de agrupación, no de datos diferentes.
- "Más dimensiones de agrupación siempre significan un mejor informe." La sobreagrupación fragmenta los datos en filas demasiado granulares para razonar; elige las dos o tres dimensiones que respondan a tu pregunta real.
- "Los datos de uso están disponibles en tiempo real." Los datos de uso y costo tienen latencia de ingesta, por lo que la actividad muy reciente puede no aparecer todavía, lo que importa si estás creando alertas sobre ellos.
Preguntas Frecuentes
¿Cuál es la diferencia entre uso y costo en la API de Administración?
- Uso es un recuento de tokens, desglosado por tipo (entrada no cacheada, entrada cacheada, creación de caché, salida).
- Costo es el uso multiplicado por el precio, expresado en dólares, con la misma granularidad que el uso.
- Separarlos te permite reevaluar el uso histórico o auditar una anomalía de costos hasta sus recuentos de tokens.
¿Por qué la API separa los tokens de entrada cacheados y no cacheados en lugar de reportar un total de entrada?
Porque se facturan de manera completamente diferente. Los tokens de entrada cacheados tienen descuento, los no cacheados no, y los tokens de creación de caché tienen una prima, por lo que agruparlos en un solo número ocultaría la mayor parte de la señal que necesita una investigación de costos.
¿Qué son los tokens de creación de caché y por qué cuestan más que la entrada no cacheada?
Los tokens de creación de caché son lo que pagas cuando escribes contenido nuevo en la caché de prompt por primera vez. La prima refleja el trabajo adicional de preparar ese contenido para una reutilización rápida, y se amortiza una vez que las solicitudes posteriores lo leen a la tarifa de caché con descuento.
¿Qué significa "agrupación" en el contexto de un informe de uso?
- Es análogo a
GROUP BYde SQL: eliges dimensiones (clave de API, espacio de trabajo, modelo, nivel de servicio y otras) y la API devuelve una fila por cada combinación única. - Más dimensiones de agrupación producen filas más numerosas y finamente detalladas.
- Elegir la agrupación correcta es lo que convierte el uso bruto en un informe legible.
¿Son los datos de la API de Administración los mismos que veo en las páginas de Uso y Costos de la Consola?
Sí, ambos leen de los mismos registros de uso subyacentes. Las diferencias que notes son casi siempre debido a diferentes ventanas de tiempo, zonas horarias o opciones de agrupación, en lugar de datos subyacentes diferentes.
¿Un mayor recuento de tokens siempre significa un mayor costo?
No necesariamente. Una solicitud grande de entrada no cacheada y una solicitud pequeña centrada en la salida pueden costar cantidades similares, ya que los tokens de salida se facturan al precio más alto de los cuatro cubos. El recuento de tokens y el costo en dólares solo se mueven al unísono cuando la mezcla de tokens se mantiene constante.
¿Qué es el nivel de servicio y por qué aparece en los datos de uso?
El nivel de servicio refleja cómo se enrutó una solicitud, por ejemplo, procesamiento estándar frente a procesamiento por lotes o prioritario, y cada nivel puede tener un precio diferente. Agrupar por nivel de servicio te permite ver cuánto de tu gasto proviene de cada opción de enrutamiento.
¿Puedo usar la API de Administración para ver los costos anteriores a que comenzara a monitorearlos activamente?
Sí, dentro de la ventana de retención de datos de la plataforma. Esa es una de las principales ventajas de una API histórica y agrupada en lugar de un panel solo en vivo: puedes reconstruir los gastos de un período que no estabas observando de cerca.
¿Por qué consultaría el uso sin pedir también el costo?
Las consultas solo de uso son útiles cuando deseas aplicar tu propio modelo de precios, por ejemplo, simulando "cuánto habría costado este mes con una tarifa diferente", o cuando estás diagnosticando un problema de volumen de tokens que es independiente del precio.
¿Cuál es el error de razonamiento más común que cometen las personas con estos datos?
Asumir que el uso y el costo siempre se mueven juntos. Cambios de precios, descuentos o un cambio en la mezcla de tokens (más lecturas cacheadas, menos no cacheadas) pueden cambiar el costo sin un cambio proporcional en los recuentos brutos de tokens, y viceversa.
¿Necesito construir mi propio panel para utilizar estos datos?
No necesariamente para preguntas ad hoc, las páginas de Uso y Costos de la Consola cubren esas. Pero para informes recurrentes, reparto de gastos (chargeback) o pronósticos, la mayoría de los equipos terminan construyendo un pequeño pipeline sobre la API de Administración para que los datos aterricen en un lugar consultable junto con otras métricas de negocio.
¿Cómo se relaciona este modelo de cubos con un modelo de reparto de gastos (chargeback) entre equipos?
Un modelo de reparto de gastos es una capa de gobernanza construida sobre los mismos datos: toma el uso y el costo por clave de API o por espacio de trabajo, y aplica una política sobre cómo se factura a los equipos internos. Los cubos de tokens subyacentes no cambian, solo cómo los atribuyes y los divides.
Relacionado
- Fundamentos de Seguimiento de Uso y Costos - obtén tu primer informe de uso y ve el modelo de cubos en una respuesta real.
- Consultar Uso por Clave de API y Espacio de Trabajo con la API de Administración - aplica dimensiones de agrupación para aislar una sola clave o espacio de trabajo.
- Creación de un Panel de Costos a partir de Desgloses de Tokens No Cacheados, Cacheados y de Salida - convierte estos cubos en un panel que un equipo de finanzas pueda leer.
- Comparación: API de Administración vs. Páginas de Uso y Costos de la Consola - decide cuándo el panel es suficiente y cuándo necesitas la API.
- Plantilla ADR: Un Modelo de Reparto de Gastos para Uso de Claves de API Multi-Equipo - ve cómo este modelo de cubos se convierte en una política de facturación por equipo.
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 de SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.