API de Uso y Costo
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.
La API de Administración de Uso y Costo proporciona acceso programático y granular a 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 Claude.
Esta API te permite monitorear, analizar y optimizar mejor tus implementaciones de Claude:
- Seguimiento Preciso de Uso: Obtén conteos precisos de tokens y patrones de uso en lugar de depender únicamente del conteo de tokens de respuesta
- Reconciliación de Costos: Haz coincidir 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
Se requiere clave de API de administrador
Esta API es parte de la API de Administración. Estos endpoints requieren una clave de API de Administrador (que comienza con sk-ant-admin...) que difiere de las claves de API estándar. Solo los miembros de la organización con el rol de administrador pueden aprovisionar claves de API de Administrador a través de la Consola Claude.
Soluciones de socios
Las principales plataformas de observabilidad ofrecen integraciones listas para usar para monitorear el uso y costo de tu API Claude, sin escribir código personalizado. Estas integraciones proporcionan paneles de control, alertas y análisis para ayudarte a gestionar el uso de tu API de manera efectiva.
Datadog
Observabilidad LLM con trazado automático y monitoreo
Grafana Cloud
Integración sin agente para observabilidad LLM fácil con paneles de control y alertas listos para usar
Honeycomb
Consultas avanzadas y visualización a través de OpenTelemetry
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"Establece un encabezado User-Agent para integraciones
Si estás construyendo una integración, establece tu encabezado User-Agent para ayudarnos a entender los patrones de uso:
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: Agregar datos de uso en intervalos fijos (
1m,1h, o1d) - Seguimiento de tokens: Medir tokens de entrada no cacheados, entrada cacheada, creación de caché y tokens de salida
- Filtrado y agrupación: Filtrar por clave de API, espacio de trabajo, modelo, nivel de servicio o ventana de contexto, y agrupar resultados por estas dimensiones
- Uso de herramientas del servidor: Rastrear 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-5-20250929&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"Filtrar 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" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"Para recuperar los IDs de claves de API de tu organización, usa el endpoint Listar Claves de API.
Para recuperar los IDs de espacios de trabajo de tu organización, usa el endpoint Listar Espacios de Trabajo, o encuentra los IDs de espacios de trabajo de tu organización en la Consola Anthropic.
Límites de granularidad temporal
| Granularidad | Límite Predeterminado | Límite Máximo | Caso de Uso |
|---|---|---|---|
1m | 60 buckets | 1440 buckets | Monitoreo en tiempo real |
1h | 24 buckets | 168 buckets | Patrones diarios |
1d | 7 buckets | 31 buckets | Reportes semanales/mensuales |
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 pequeñas (centavos)
- Tipos de costo: Rastrear uso de tokens, búsqueda web y costos de ejecución de código
- Agrupación: Agrupar 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.
Los costos del Nivel de Prioridad usan un modelo de facturación diferente y no están incluidos en el endpoint de costo. Rastrea el uso del Nivel de Prioridad a través del endpoint de uso en su lugar.
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:
- Haz tu solicitud inicial
- Si
has_moreestrue, usa el valornext_pageen tu próxima solicitud - Continúa hasta que
has_moreseafalse
# 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..."
# Próxima 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: Rastrear tendencias de consumo de tokens
- Atribución de costos: Asignar gastos por espacio de trabajo para contracargos
- Eficiencia de caché: Medir y optimizar el caché de prompts
- Monitoreo de presupuesto: Configurar alertas para umbrales de gasto
- Exportación CSV: Generar 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 completarse 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, descargar datos paginados), el sondeo más frecuente es aceptable. Cachea 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 costos atribuidos al espacio de trabajo predeterminado tienen un valor null para workspace_id.
¿Cómo obtengo desgloses de costo por usuario para Claude Code?
Usa la API de Análisis de Claude Code, que proporciona costos estimados por usuario y métricas de productividad sin las limitaciones de rendimiento de desglosar costos por muchas claves de API. Para uso general de API con muchas claves, usa la API de Uso para rastrear el consumo de tokens como un proxy de costo.
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 - Optimizar costos con caché
- Procesamiento por lotes - 50% de descuento en solicitudes por lotes
- Límites de velocidad - Entender niveles de uso