Report avanzati sui consumi
In questa pagina
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’uso | Granularità consigliata |
|---|---|
| Report mensile | MONTH |
| Tracciamento giornaliero | DAY |
| Analisi dei picchi | HOUR o QUARTER_HOUR |
| Debug in tempo reale | MINUTE |
| Analisi dettagliata incidenti | SECOND |
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) egroupBy: ["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