Analytics d'utilisation

Comprendre votre consommation API

L’endpoint d’analytics est l’outil le plus puissant de la Management API pour comprendre votre utilisation. Il permet d’analyser la consommation par modèle, par période et avec différentes granularités temporelles — des données essentielles pour optimiser vos coûts et dimensionner votre infrastructure.

Endpoint d’analyse

L’analyse d’utilisation se fait via une requête POST :

POST /v1/billing/teams/{teamId}/usage

Structure de la requête

{
  "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"]
  }
}

Cette requête demande la somme des tokens consommés par jour, ventilée par modèle, pour le mois de mars 2026 en UTC.

Paramètres de la requête

timeRange

Définit la période d’analyse :

• startTime : début de la période (format YYYY-MM-DD HH:MM:SS)
• endTime : fin de la période (format identique)
• timezone : fuseau horaire pour l’interprétation des dates (ex: UTC, Europe/Paris)

timeUnit

La granularité temporelle des résultats. Les options disponibles sont :

• MONTH : agrégation mensuelle
• CALENDAR_WEEK : agrégation par semaine calendaire
• DAY : agrégation quotidienne
• HOUR : agrégation horaire
• QUARTER_HOUR : agrégation par quart d’heure
• MINUTE : agrégation par minute
• SECOND : agrégation par seconde

Choisissez la granularité adaptée à votre besoin. Pour un rapport mensuel, DAY est suffisant. Pour debugger un pic de consommation, HOUR ou QUARTER_HOUR donnent plus de détails.

values

Les métriques à calculer, avec leur fonction d’agrégation :

"values": [
  {"name": "tokens", "aggregation": "SUM"},
  {"name": "tokens", "aggregation": "AVG"},
  {"name": "latency", "aggregation": "P99"}
]

Les fonctions d’agrégation disponibles :

• SUM : somme totale
• AVG : moyenne
• MIN : valeur minimale
• MAX : valeur maximale
• P50 : médiane (percentile 50)
• P90 : percentile 90
• P99 : percentile 99
• COUNT : nombre d’occurrences
• COUNT_DISTINCT : nombre de valeurs distinctes

groupBy

Ventile les résultats par dimension. Actuellement, le groupement par model est disponible, ce qui permet de voir la consommation séparée pour chaque modèle (grok-4.20-reasoning, grok-4.20-mini, etc.).

Exemples pratiques

Consommation quotidienne du mois en cours

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"]
    }
  }'

Nombre de requêtes par heure

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"]
    }
  }'

Latence P99 par modèle

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"]
    }
  }'

Points clés à retenir

• L’endpoint POST /v1/billing/teams/{teamId}/usage centralise toutes les analytics
• 7 granularités temporelles disponibles, de SECOND à MONTH
• 9 fonctions d’agrégation : SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
• Le paramètre groupBy: ["model"] ventile les résultats par modèle
• Utilisez le fuseau horaire Europe/Paris pour des rapports alignés sur vos horaires de travail