Analytics d'utilisation

Comprendre votre consommation API

Une facture vous dit combien vous avez dépensé ; cet endpoint vous dit pourquoi. C’est toute la différence entre constater et pouvoir agir : la consommation s’y décompose par modèle, par période et à la granularité de votre choix, ce qui permet de rattacher une hausse à un modèle précis et à un moment précis.

Sa syntaxe est plus riche que le reste de la Management API — trois blocs de paramètres à combiner — mais elle se résume à trois questions : sur quelle période, à quelle finesse, et quelle mesure. Le reste de cette leçon les traite dans cet ordre. 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. Lisez-la comme un gabarit : en pratique, vous ne changerez que trois choses d’un rapport à l’autre — la période, l’unité de temps et la métrique — le reste de la structure demeurant identique.

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é d’après la durée du phénomène que vous cherchez, et non d’après la longueur de la période analysée. Un rapport mensuel se lit très bien en DAY ; un pic de dix minutes disparaît complètement à cette échelle et n’apparaît qu’en QUARTER_HOUR. Descendre trop bas a aussi un coût — le volume de points retournés croît vite, et le bruit avec lui.

values

Le choix de la fonction d’agrégation change la question posée, et c’est là que les percentiles méritent votre attention. AVG sur la latence donne une moyenne rassurante que personne n’expérimente vraiment ; P99 donne le temps d’attente subi par vos utilisateurs les plus malchanceux — c’est-à-dire ceux qui se plaignent. Pour un coût, SUM ; pour une performance, un percentile.

"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-0309-reasoning, grok-4.3, 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