API de uso y costos

La API de administración de uso y costos (Usage & Cost Admin API) proporciona acceso programático y granular a los datos históricos de uso y costos de la API de tu organización. Estos datos son similares a la información disponible en las páginas de Uso y Costo de la Claude Console.

Esta API te permite monitorear, analizar y optimizar mejor tus implementaciones de Claude:

• Seguimiento preciso del uso: Obtén conteos de tokens y patrones de uso precisos en lugar de depender únicamente del conteo de tokens de las respuestas
• Conciliación de costos: Haz coincidir los registros internos con la facturación de Anthropic para los equipos de finanzas y contabilidad
• Rendimiento y mejora del producto: Monitorea el rendimiento del producto mientras mides si los cambios en el sistema lo han mejorado, o configura alertas
• Optimización del límite de velocidad: Optimiza funciones como el almacenamiento en caché de prompts o prompts específicos para aprovechar al máximo tu capacidad asignada.
• Análisis avanzado: Realiza análisis de datos más profundos que los disponibles en la Console

Las organizaciones de Claude Enterprise usan en su lugar una clave de API de Analytics con una API diferente; consulta ¿Qué API necesitas?.

¿Qué API necesitas?

Anthropic proporciona informes de costos y uso a través de dos APIs, según el producto de Claude que administre tu organización:

Las organizaciones principales de Claude Enterprise no aparecen en la Claude Console y no tienen claves de API de administración, por lo que para ellas la clave de API de Analytics es la única vía para acceder a estos datos. Consulta APIs de Analytics para saber cómo crear cada tipo de clave y a qué planes se aplican los datos de costos de Claude Enterprise.

Soluciones de socios

Las principales plataformas de observabilidad ofrecen integraciones listas para usar para monitorear el uso y los costos de tu API de Claude, sin escribir código personalizado. Estas integraciones proporcionan paneles, alertas y análisis para ayudarte a administrar el uso de tu API de manera efectiva.

Inicio rápido

Obtén el uso diario de tu organización durante los últimos 7 días:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-15T00:00:00Z&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

API de uso

Realiza un seguimiento del consumo de tokens en toda tu organización con desgloses detallados por modelo, espacio de trabajo y nivel de servicio con el endpoint /v1/organizations/usage_report/messages.

Conceptos clave

• Intervalos de tiempo (time buckets): Agrega los datos de uso en intervalos fijos (1m, 1h o 1d)
• Seguimiento de tokens: Mide los tokens de entrada sin caché, de entrada en caché, de creación de caché y de salida
• Filtrado y agrupación: Filtra por clave de API, espacio de trabajo, modelo, nivel de servicio, ventana de contexto, residencia de datos o velocidad (beta), y agrupa los resultados por estas dimensiones
• Uso de herramientas de servidor: Realiza un seguimiento del uso de herramientas del lado del servidor, como la búsqueda web

Para obtener los detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de uso.

Ejemplos básicos

Uso diario por modelo

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Uso por hora con filtrado

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-15T00:00:00Z&\
ending_at=2025-01-15T23:59:59Z&\
models[]=claude-opus-5&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Filtrar el uso por claves de API y espacios de trabajo

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\
api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Residencia de datos

Realiza un seguimiento de tus controles de residencia de datos agrupando y filtrando el uso con la dimensión inference_geo. Esto es útil para verificar el enrutamiento geográfico en toda tu organización.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=inference_geo&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

También puedes filtrar por una geografía específica. Los valores válidos son global, us y not_available:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
inference_geos[]=us&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Modo rápido (vista previa de investigación)

Realiza un seguimiento del uso del modo rápido agrupando y filtrando con la dimensión speed. Esto es útil para monitorear el uso del modo estándar frente al modo rápido.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

También puedes filtrar por una velocidad específica. Los valores válidos son standard y fast:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
speeds[]=fast&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Límites de granularidad temporal

API de costos

Obtén desgloses de costos a nivel de servicio en USD con el endpoint /v1/organizations/cost_report.

Conceptos clave

• Moneda: Todos los costos en USD, reportados como cadenas decimales en las unidades más bajas (centavos)
• Tipos de costos: Realiza un seguimiento de los costos de uso de tokens, búsqueda web y ejecución de código
• Agrupación: Agrupa los costos por espacio de trabajo o descripción para obtener desgloses detallados. Al agrupar por description, las respuestas incluyen campos analizados como model e inference_geo
• Intervalos de tiempo: Solo granularidad diaria (1d)

Para obtener los detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de costos.

Ejemplo básico

curl "https://api.anthropic.com/v1/organizations/cost_report?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
group_by[]=workspace_id&\
group_by[]=description" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Paginación

Ambos endpoints admiten paginación para conjuntos de datos grandes:

1. Realiza tu solicitud inicial.
2. Si has_more es true, usa el valor next_page en tu siguiente solicitud.
3. Continúa hasta que has_more sea false.

# Primera solicitud
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

# La respuesta incluye: "has_more": true, "next_page": "page_xyz..."

# Siguiente solicitud con paginación
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7&\
page=page_xyz..." \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Casos de uso comunes

Explora implementaciones detalladas en el Claude Cookbook:

• Informes de uso diario: Realiza un seguimiento de las tendencias de consumo de tokens
• Atribución de costos: Asigna gastos por espacio de trabajo para la refacturación interna
• Eficiencia de la caché: Mide y optimiza el almacenamiento en caché de prompts
• Monitoreo de presupuesto: Configura alertas para umbrales de gasto
• Exportación a CSV: Genera informes para los equipos de finanzas

Preguntas frecuentes

¿Qué tan actualizados están los datos?

Los datos de uso y costos suelen aparecer dentro de los 5 minutos posteriores a la finalización de la solicitud a la API, aunque ocasionalmente los retrasos pueden ser mayores.

¿Cuál es la frecuencia de sondeo recomendada?

La API admite un sondeo de una vez por minuto para un uso sostenido. Para ráfagas cortas (por ejemplo, al descargar datos paginados), es aceptable un sondeo más frecuente. Almacena en caché los resultados para los paneles que necesiten actualizaciones frecuentes.

¿Cómo realizo un seguimiento del uso de la ejecución de código?

Los costos de ejecución de código aparecen en el endpoint de costos agrupados bajo Code Execution Usage en el campo de descripción. La ejecución de código no se incluye en el endpoint de uso.

¿Cómo realizo un seguimiento del uso de Priority Tier?

Filtra o agrupa por service_tier en el endpoint de uso y busca el valor priority. Los costos de Priority Tier no están disponibles en el endpoint de costos.

¿Qué sucede con el uso del playground?

El uso de la API desde el playground en la Claude Console (y desde el Workbench heredado antes de él) no está asociado a una clave de API, por lo que api_key_id será null incluso al agrupar por esa dimensión.

¿Cómo se representa el espacio de trabajo predeterminado?

El uso y los costos atribuidos al espacio de trabajo predeterminado tienen un valor null para workspace_id.

¿Cómo obtengo desgloses de costos por usuario para Claude Code?

Usa la API de Analytics de Claude Code, que proporciona costos estimados por usuario y métricas de productividad sin las limitaciones de rendimiento de desglosar los costos por muchas claves de API. Para el uso general de la API con muchas claves, usa la API de uso para realizar un seguimiento del consumo de tokens como indicador aproximado del costo.

Ver también

Usa las APIs de uso y costos para ofrecer una mejor experiencia a tus usuarios, administrar los costos y preservar tu límite de velocidad. Obtén más información sobre algunas de estas otras funciones:

• API de administración
• Referencia de la API de administración
• APIs de Analytics - Qué API de analytics y tipo de clave necesita tu organización
• Precios
• Almacenamiento en caché de prompts - Optimiza los costos con el almacenamiento en caché
• Procesamiento por lotes - 50% de descuento en solicitudes por lotes
• Límites de velocidad - Comprende los niveles de uso
• API de límites de velocidad - Consulta tus límites de velocidad configurados
• Residencia de datos - Controla la geografía de la inferencia