Costos de la API de Claude: una nueva API muestra quién gasta tokens y en qué

El 29 de octubre, Anthropic lanzó en beta la Usage and Cost Analytics API, una nueva API para informar del consumo de tokens y de los costos de la API de Claude en una organización. Según las Claude Release Notes, la Usage and Cost API anterior pasa a ser una API «legacy» desde ese día, aunque sigue teniendo soporte.

¿Qué hay de nuevo en los informes de costos de la API de Claude?

La API tiene dos endpoints:

1. GET /v1/organizations/analytics/usage devuelve el número de tokens y de solicitudes,
2. GET /v1/organizations/analytics/cost devuelve el costo en USD.

Lo más interesante es cómo podemos segmentar estos datos. En una sola solicitud agrupamos los resultados por hasta cinco dimensiones: modelo, workspace, clave de API, nivel de servicio, ventana de contexto, región de inferencia, producto y el llamado «actor», es decir, quien realmente envió la solicitud. El actor puede ser un usuario, una cuenta de servicio, una identidad de AWS o de Google Cloud y, si no hay ninguno de estos, la propia clave de API.

Los resultados llegan como un ranking, ordenado por defecto de mayor a menor consumo. Así que la pregunta «¿qué claves de API gastaron más este mes?» es una sola solicitud, no un script que junta datos de varios informes.

Para Claude Code hay una receta lista: el costo por usuario se obtiene con una solicitud con products[]=claude_code&group_by[]=actor. Después de las mediciones según las cuales los resúmenes ocultos de los agentes se comen entre el 16 y el 22 % del costo de una sesión, esto llega en muy buen momento.

¿Cómo es una solicitud?

Un ejemplo de la documentación: el consumo diario de tokens de la primera semana de septiembre, por separado para cada modelo.

curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
time_bucket_width=1d&\
group_by[]=model&\
limit=10" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

Cada fila tiene tres partes: el intervalo de tiempo, group con las dimensiones y usage (o cost) con las cifras. En usage encontramos, entre otras cosas, los tokens de entrada sin caché, los tokens escritos y leídos de la caché, los tokens de salida, el número de búsquedas web y el número de solicitudes. Lo mismo está disponible a través del SDK y de la CLI ant (ant beta:organization:analytics:usage list).

Algunos detalles:

1. Los intervalos de tiempo son de 1 minuto, 1 hora o 1 día, todo en UTC.
2. Una solicitud abarca como máximo 31 días, y con intervalos de un minuto solo 24 horas.
3. Los datos llegan hasta el 1 de enero de 2026 y como mucho 365 días atrás.
4. Una página de resultados tiene de 1 a 1000 filas (20 por defecto).

¿Qué muestra el endpoint de costos?

El endpoint /cost devuelve dos importes: amount, es decir, el costo después de descuentos, pero antes de restar los créditos, y list_amount, el costo a precios de lista. Los importes se dan en centavos con seis decimales, así que "41280.000000" significa 412,80 USD.

Dos dimensiones adicionales, cost_type y token_type, desglosan el costo en tokens de cada tipo, búsqueda web, ejecución de código y sesiones. No cuentan para el límite de cinco dimensiones.

¿A qué hay que prestar atención?

Primero, al retraso. Los datos se actualizan normalmente en 4 horas y a veces en hasta 24 horas, mientras que en la antigua Usage and Cost API solían aparecer en 5 minutos. Para alertas «aquí y ahora», mejor buscar otra cosa.

Segundo, a las correcciones. Los valores pueden cambiar todavía durante unos 7 días después del final del mes natural, así que las sumas definitivas de octubre las tendremos hacia el 7 de noviembre.

Tercero, al Priority Tier. Las solicitudes dentro de un Priority Tier contratado aparecen en el consumo, pero su costo en tokens es cero, porque la tarifa del compromiso se factura por separado.

Cuarto, al acceso. La API solo funciona para organizaciones: en la Claude Console con una clave de Admin API y en Claude Enterprise con una clave con el permiso read:analytics. Las cuentas individuales no pueden usarla. También funciona en Claude Platform on AWS y en Claude Models on Google Cloud, con la autenticación de cada nube.

¿Es algo nuevo en el mundo de la IA?

Los informes de costos en la Claude Console ya existían. Lo nuevo es que los mismos endpoints y campos sirven tanto a las organizaciones de la Claude Console como a Claude Enterprise. Para Enterprise, además, desaparece un límite: los informes antiguos devolvían solo los 100 grupos más grandes de cada intervalo, los nuevos los devuelven todos.

Es otro paso de Anthropic hacia el control del gasto, justo después de Claude smart reports, que muestran qué hizo un equipo con Claude y cuánto costó.

Preguntas frecuentes

¿Cómo consultar los costos de la API de Claude?

En la Claude Console, en las páginas Usage y Cost, o de forma programática con la Usage and Cost Analytics API (endpoint /v1/organizations/analytics/cost) y una clave de Admin API. Cada respuesta de la API incluye además un bloque usage con el número de tokens de esa solicitud.

¿Dejará de funcionar la antigua Usage and Cost API?

A 29 de octubre, no. Según las Claude Release Notes tiene el estado «legacy», pero sigue teniendo soporte, y la documentación incluye una guía de migración.

¿Cómo saber cuánto gasta cada usuario de Claude Code?

Con el endpoint de costos y los parámetros products[]=claude_code&group_by[]=actor. Las organizaciones de la Claude Console también pueden usar la Claude Code Analytics API, que es independiente.