Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Report avanzati sui consumi

Lezione 10 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Costruire report sui consumi
  2. Report mensile comparativo
  3. Rilevamento delle anomalie
  4. Suddivisione per modello
  5. Report settimanale automatizzato
  6. Granularità e prestazioni
  7. Punti chiave

Costruire report sui consumi

I dati di consumo che nessuno consulta sono inutili. Un report è utile solo se risponde a una domanda concreta, e le domande sono solo tre: sta aumentando? È successo qualcosa di anomalo? Dove stanno finendo i soldi?

Le prossime tre sezioni affrontano queste domande in quest’ordine preciso. Ognuna produce un numero su cui puoi agire, non solo un altro grafico.

Report mensile comparativo

Il consumo ha senso solo se confrontato. 400 $ in un mese non sono né buoni né cattivi in termini assoluti: ciò che conta è sapere se seguono un mese da 200 $ o uno da 600 $. Contestualizza sempre le variazioni con ciò che sai dell’attività: un aumento del 40% dopo il lancio di una funzionalità è normale, lo stesso aumento senza novità richiede di aprire la sezione successiva.

import requests
import json

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

def get_monthly_usage(year, month):
    """Retrieves total consumption for a given month."""
    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()

# Compare March and April 2026
march = get_monthly_usage(2026, 3)
april = get_monthly_usage(2026, 4)

print("=== Comparative Report March vs April 2026 ===")
print(json.dumps(march, indent=2))
print(json.dumps(april, indent=2))

Rilevamento delle anomalie

La deviazione standard definisce qui cosa è “anomalo” senza bisogno di impostare una soglia arbitraria: un giorno che supera di due deviazioni standard la tua media esce dal pattern abituale, indipendentemente dal tuo volume. Questo è il metodo che si adatta automaticamente man mano che la tua attività cresce, laddove una soglia in dollari diventerebbe obsoleta il mese successivo.

import requests
import statistics

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

# Retrieve daily consumption for the month
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  # Threshold at 2 standard deviations

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

Suddivisione per modello

Questo è il report che ripaga di più, perché punta ad azioni concrete. Il costo totale non ti dice cosa fare; la suddivisione per modello sì: rivela compiti semplici instradati verso il modello più costoso, che rappresentano i risparmi più facili da realizzare sulla fattura API.

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

Questa analisi può rivelare opportunità di ottimizzazione: se una grande parte delle tue richieste usa grok-4.20-0309-reasoning per compiti semplici, passare a grok-4.3 potrebbe ridurre significativamente i costi.

Report settimanale automatizzato

La consegna automatica cambia la natura dell’esercizio: un report che devi andare a cercare viene consultato solo dopo l’incidente, un report che arriva viene letto prima. La cadenza settimanale è quella giusta per il consumo API: abbastanza frequente da intercettare derive prima della fattura, abbastanza distanziata da farti continuare ad aprirlo.

import requests
from datetime import datetime, timedelta

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

# Previous week
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"=== Weekly Report {start.date()} → {end.date()} ===")

# Format report for email/Slack
# ... send via your preferred notification tool

Granularità e prestazioni

Scegliere la granularità giusta

Caso d’usoGranularità consigliata
Report mensileMONTH
Tracciamento giornalieroDAY
Analisi dei picchiHOUR o QUARTER_HOUR
Debug in tempo realeMINUTE
Analisi dettagliata incidentiSECOND

Più fine è la granularità, maggiore è la quantità di dati restituiti: nell’arco di un mese, la granularità SECOND produce milioni di punti, con tempi di risposta e consumo di memoria corrispondenti. La regola empirica è scegliere la granularità in base alla durata di ciò che stai cercando: un picco di pochi minuti è invisibile con granularità MONTH e annegato nel rumore con granularità SECOND.

Punti chiave

  • Combina SUM (totale), COUNT (conteggio) e groupBy: ["model"] per report completi
  • Il rilevamento anomalie con deviazione standard identifica i giorni di sovraconsumo
  • La suddivisione per modello rivela opportunità di ottimizzazione dei costi
  • Adatta la granularità temporale al caso d’uso: MONTH per i report, HOUR per il debug
  • Automatizza i report settimanali per tenere d’occhio i consumi