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.
//
Busca en todas las páginas de la documentación
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.
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.
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.
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.
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.
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.
GROUP BY de 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.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.
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.
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.
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.
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.
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.
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.
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.
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.
Revisado por Chris St. John·Última actualización: 16 jul 2026