Ir al contenido principal
Español— Elegir un idioma
Menú

Analíticas de uso

Lección 9 de 14 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Entiende tu consumo de API
  2. Extremo de análisis
  3. Parámetros de la petición
  4. Ejemplos prácticos
  5. Puntos clave

Entiende tu consumo de API

Panel de uso en la consola de xAI 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.

7
Unidades de tiempo
9
Agregaciones
POST
Método HTTP
groupBy
Desglose por modelo

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}/usage centraliza 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/Paris para informes alineados con tu horario laboral