API de Uso y Costo

La API de Administración de Uso y Costo proporciona acceso programático y granular a los datos históricos de uso y costo de la API para tu organización. Estos datos son similares a la información disponible en las páginas de Uso y Costo de la Consola de Anthropic.

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

• Seguimiento Preciso de Uso: Obtén conteos de tokens precisos y patrones de uso en lugar de depender únicamente del conteo de tokens de respuesta
• Reconciliación de Costos: Coincide registros internos con la facturación de Anthropic para equipos de finanzas y contabilidad
• Rendimiento y mejora del producto: Monitorea el rendimiento del producto mientras mides si los cambios al sistema lo han mejorado, o configura alertas
• Optimización de límites de velocidad y Nivel de Prioridad: Optimiza características como caché de prompts o prompts específicos para aprovechar al máximo la capacidad asignada, o compra capacidad dedicada.
• Análisis Avanzado: Realiza análisis de datos más profundos que los disponibles en la Consola

​

Soluciones de socios

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

​

Inicio rápido

Obtén el uso diario de tu organización para 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

User-Agent: TuApp/1.0.0 (https://tuapp.com)

​

API de Uso

Rastrea el 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

• Buckets de tiempo: Agrega datos de uso en intervalos fijos (1m, 1h, o 1d)
• Seguimiento de tokens: Mide tokens de entrada no cacheados, entrada cacheada, creación de caché y tokens de salida
• Filtrado y agrupación: Filtra por clave de API, espacio de trabajo, modelo, nivel de servicio o ventana de contexto, y agrupa resultados por estas dimensiones
• Uso de herramientas del servidor: Rastrea el uso de herramientas del lado del servidor como búsqueda web

Para detalles completos de parámetros y 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_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-sonnet-4-20250514&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

​

Límites de granularidad de tiempo

​

API de Costo

Recupera 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 unidades más bajas (centavos)
• Tipos de costo: Rastrea costos de uso de tokens, búsqueda web y ejecución de código
• Agrupación: Agrupa costos por espacio de trabajo o descripción para desgloses detallados
• Buckets de tiempo: Solo granularidad diaria (1d)

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

​

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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

​

Paginación

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

1. Haz 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_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..." \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

​

Casos de uso comunes

Explora implementaciones detalladas en anthropic-cookbook:

• Reportes de uso diario: Rastrea tendencias de consumo de tokens
• Atribución de costos: Asigna gastos por espacio de trabajo para contracargos
• Eficiencia de caché: Mide y optimiza el caché de prompts
• Monitoreo de presupuesto: Configura alertas para umbrales de gasto
• Exportación CSV: Genera reportes para equipos de finanzas

​

Preguntas frecuentes

​

¿Qué tan frescos son los datos?

Los datos de uso y costo típicamente aparecen dentro de 5 minutos de la finalización de la solicitud de API, aunque ocasionalmente los retrasos pueden ser más largos.

​

¿Cuál es la frecuencia de sondeo recomendada?

La API soporta sondeo una vez por minuto para uso sostenido. Para ráfagas cortas (por ejemplo, descarga de datos paginados), el sondeo más frecuente es aceptable. Almacena en caché los resultados para paneles de control que necesitan actualizaciones frecuentes.

​

¿Cómo rastrea el uso de ejecución de código?

Los costos de ejecución de código aparecen en el endpoint de costo agrupados bajo Code Execution Usage en el campo de descripción. La ejecución de código no está incluida en el endpoint de uso.

​

¿Cómo rastrea el uso del Nivel de Prioridad?

Filtra o agrupa por service_tier en el endpoint de uso y busca el valor priority. Los costos del Nivel de Prioridad no están disponibles en el endpoint de costo.

​

¿Qué pasa con el uso de Workbench?

El uso de API desde Workbench no está asociado con una clave de API, por lo que api_key_id será null incluso cuando se agrupe 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.

​

Ver también

Las APIs de Uso y Costo pueden usarse para ayudarte a entregar una mejor experiencia para tus usuarios, ayudarte a gestionar costos y preservar tu límite de velocidad. Aprende más sobre algunas de estas otras características:

• Resumen de la API de Administración
• Referencia de la API de Administración
• Precios
• Caché de prompts - Optimiza costos con caché
• Procesamiento por lotes - 50% de descuento en solicitudes por lotes
• Límites de velocidad - Entiende los niveles de uso