Analíticas de uso
En esta página
Entiende tu consumo de API
Una factura te dice cuánto has gastado; este extremo te explica por qué. Esa es la diferencia entre observar y actuar: el consumo se desglosa por modelo, por periodo y con la granularidad que elijas, lo que te permite vincular un pico de tráfico a un modelo concreto en un momento específico.
Su sintaxis es más rica que la del resto de la API de gestión —tres bloques de parámetros para combinar—, pero se reduce a tres preguntas: ¿en qué periodo?, ¿con qué granularidad? y ¿qué medida? Esta lección las aborda en ese orden. Te permite analizar el consumo por modelo, por periodo y con distintas granularidades temporales, datos esenciales para optimizar costes y dimensionar tu infraestructura.
Extremo de análisis
El análisis de uso se realiza mediante una petición POST:
POST /v1/billing/teams/{teamId}/usage
Estructura de la petición
{
"analyticsRequest": {
"timeRange": {
"startTime": "2026-03-01 00:00:00",
"endTime": "2026-04-01 00:00:00",
"timezone": "UTC"
},
"timeUnit": "DAY",
"values": [
{"name": "tokens", "aggregation": "SUM"}
],
"groupBy": ["model"]
}
}
Esta petición solicita la suma de tokens consumidos por día, desglosada por modelo, para marzo de 2026 en UTC. Trátala como una plantilla: en la práctica, solo cambiarás tres cosas de un informe a otro —el periodo, la unidad de tiempo y la métrica—, mientras que el resto de la estructura permanece idéntica.
Parámetros de la petición
timeRange
Define el periodo de análisis:
- startTime: inicio del periodo (formato
YYYY-MM-DD HH:MM:SS) - endTime: fin del periodo (mismo formato)
- timezone: zona horaria para la interpretación de las fechas (p. ej.,
UTC,Europe/Paris)
timeUnit
La granularidad temporal de los resultados. Las opciones disponibles son:
- MONTH: agregación mensual
- CALENDAR_WEEK: agregación por semana natural
- DAY: agregación diaria
- HOUR: agregación horaria
- QUARTER_HOUR: agregación por cuarto de hora
- MINUTE: agregación por minuto
- SECOND: agregación por segundo
Elige la granularidad en función de la duración del fenómeno que buscas, no de la longitud del periodo analizado. Un informe mensual se lee bien en DAY; un pico de diez minutos desaparece por completo a esa escala y solo aparece en QUARTER_HOUR. Bajar demasiado también tiene un coste: el volumen de puntos devueltos crece rápidamente, y el ruido también.
values
La elección de la función de agregación cambia la pregunta que se formula, y aquí es donde los percentiles merecen tu atención. AVG en latencia ofrece una media tranquilizadora que nadie experimenta realmente; P99 indica el tiempo de espera que sufren tus usuarios con peor suerte —los que se quejan—. Para costes, usa SUM; para rendimiento, usa un percentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Funciones de agregación disponibles:
- SUM: suma total
- AVG: media
- MIN: valor mínimo
- MAX: valor máximo
- P50: mediana (percentil 50)
- P90: percentil 90
- P99: percentil 99
- COUNT: número de ocurrencias
- COUNT_DISTINCT: número de valores distintos
groupBy
Desglosa los resultados por dimensión. Actualmente, está disponible la agrupación por model, lo que te permite ver el consumo separado de cada modelo (grok-4.20-0309-reasoning, grok-4.3, etc.).
Ejemplos prácticos
Consumo diario del mes actual
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/usage" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"analyticsRequest": {
"timeRange": {
"startTime": "2026-04-01 00:00:00",
"endTime": "2026-05-01 00:00:00",
"timezone": "Europe/Paris"
},
"timeUnit": "DAY",
"values": [{"name": "tokens", "aggregation": "SUM"}],
"groupBy": ["model"]
}
}'
Número de peticiones por hora
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/usage" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"analyticsRequest": {
"timeRange": {
"startTime": "2026-04-03 00:00:00",
"endTime": "2026-04-04 00:00:00",
"timezone": "Europe/Paris"
},
"timeUnit": "HOUR",
"values": [{"name": "requests", "aggregation": "COUNT"}],
"groupBy": ["model"]
}
}'
Latencia P99 por modelo
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/usage" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"analyticsRequest": {
"timeRange": {
"startTime": "2026-04-01 00:00:00",
"endTime": "2026-04-04 00:00:00",
"timezone": "UTC"
},
"timeUnit": "DAY",
"values": [
{"name": "latency", "aggregation": "P99"},
{"name": "latency", "aggregation": "AVG"}
],
"groupBy": ["model"]
}
}'
Puntos clave
- El extremo
POST /v1/billing/teams/{teamId}/usagecentraliza todas las analíticas - 7 granularidades temporales disponibles, desde SECOND hasta MONTH
- 9 funciones de agregación: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- El parámetro
groupBy: ["model"]desglosa los resultados por modelo - Usa la zona horaria
Europe/Parispara informes alineados con tu horario laboral