Rapports de consommation avancés

Construire des rapports de consommation

Maintenant que vous maîtrisez l’endpoint d’analytics, voyons comment exploiter ces données pour construire des rapports utiles : comparaisons mensuelles, détection d’anomalies, et rapports automatisés pour votre équipe.

Rapport mensuel comparatif

Comparez la consommation de deux mois pour détecter les tendances :

import requests
import json

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

def get_monthly_usage(year, month):
    """Récupère la consommation totale pour un mois donné."""
    next_month = month + 1 if month < 12 else 1
    next_year = year if month < 12 else year + 1

    response = requests.post(
        f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
        headers={
            "Authorization": f"Bearer {MGMT_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "analyticsRequest": {
                "timeRange": {
                    "startTime": f"{year}-{month:02d}-01 00:00:00",
                    "endTime": f"{next_year}-{next_month:02d}-01 00:00:00",
                    "timezone": "Europe/Paris"
                },
                "timeUnit": "MONTH",
                "values": [
                    {"name": "tokens", "aggregation": "SUM"},
                    {"name": "requests", "aggregation": "COUNT"}
                ],
                "groupBy": ["model"]
            }
        }
    )
    return response.json()

# Comparer mars et avril 2026
mars = get_monthly_usage(2026, 3)
avril = get_monthly_usage(2026, 4)

print("=== Rapport comparatif Mars vs Avril 2026 ===")
print(json.dumps(mars, indent=2))
print(json.dumps(avril, indent=2))

Détection d’anomalies

Identifiez les jours avec une consommation anormalement élevée :

import requests
import statistics

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

# Récupérer la consommation quotidienne du mois
response = requests.post(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
    headers={
        "Authorization": f"Bearer {MGMT_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "analyticsRequest": {
            "timeRange": {
                "startTime": "2026-03-01 00:00:00",
                "endTime": "2026-04-01 00:00:00",
                "timezone": "Europe/Paris"
            },
            "timeUnit": "DAY",
            "values": [{"name": "tokens", "aggregation": "SUM"}]
        }
    }
)

data = response.json()
daily_values = [point.get("value", 0) for point in data.get("dataPoints", [])]

if daily_values:
    mean = statistics.mean(daily_values)
    stdev = statistics.stdev(daily_values) if len(daily_values) > 1 else 0
    threshold = mean + 2 * stdev  # Seuil à 2 écarts-types

    for i, val in enumerate(daily_values):
        if val > threshold:
            print(f"Jour {i+1} : {val} tokens (anomalie, seuil = {threshold:.0f})")

Ventilation par modèle

Analysez la répartition de consommation entre les modèles pour optimiser les coûts :

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-03-01 00:00:00",
        "endTime": "2026-04-01 00:00:00",
        "timezone": "UTC"
      },
      "timeUnit": "MONTH",
      "values": [
        {"name": "tokens", "aggregation": "SUM"},
        {"name": "cost", "aggregation": "SUM"}
      ],
      "groupBy": ["model"]
    }
  }'

Cette analyse peut révéler des opportunités d’optimisation : si une grande partie de vos requêtes utilise grok-4.20-reasoning pour des tâches simples, basculer vers grok-4.20-mini pourrait réduire significativement les coûts.

Rapport hebdomadaire automatisé

Créez un script qui envoie un résumé hebdomadaire :

import requests
from datetime import datetime, timedelta

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

# Semaine précédente
end = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
start = end - timedelta(days=7)

response = requests.post(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
    headers={
        "Authorization": f"Bearer {MGMT_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "analyticsRequest": {
            "timeRange": {
                "startTime": start.strftime("%Y-%m-%d %H:%M:%S"),
                "endTime": end.strftime("%Y-%m-%d %H:%M:%S"),
                "timezone": "Europe/Paris"
            },
            "timeUnit": "DAY",
            "values": [
                {"name": "tokens", "aggregation": "SUM"},
                {"name": "requests", "aggregation": "COUNT"}
            ],
            "groupBy": ["model"]
        }
    }
)

report = response.json()
print(f"=== Rapport hebdomadaire {start.date()} → {end.date()} ===")

# Formater le rapport pour email/Slack
# ... envoi via votre outil de notification préféré

Granularité et performance

Choisir la bonne granularité

Plus la granularité est fine, plus la quantité de données retournées est importante. Pour une période d’un mois, évitez SECOND ou MINUTE qui généreraient des millions de points de données.

Points clés à retenir

• Combinez SUM (total), COUNT (nombre) et groupBy: ["model"] pour des rapports complets
• La détection d’anomalies avec l’écart-type identifie les jours de surconsommation
• La ventilation par modèle révèle les opportunités d’optimisation des coûts
• Adaptez la granularité temporelle au cas d’usage : MONTH pour les rapports, HOUR pour le debug
• Automatisez les rapports hebdomadaires pour garder un oeil sur la consommation