Analisi dell'utilizzo
In questa pagina
Comprendi il tuo consumo API
Una fattura ti dice quanto hai speso; questo endpoint ti spiega perché. Questa è la differenza tra osservare e agire: il consumo si scompone per modello, per periodo e con la granularità che scegli, permettendoti di collegare un picco a un modello specifico in un momento preciso.
La sua sintassi è più ricca rispetto al resto della Management API: tre blocchi di parametri da combinare, ma tutto si riduce a tre domande: su quale periodo, con quale granularità e quale misura. Questa lezione li affronta in quest’ordine. Ti permette di analizzare il consumo per modello, per periodo e con diverse granularità temporali: dati essenziali per ottimizzare i costi e dimensionare la tua infrastruttura.
Endpoint di analisi
L’analisi dell’utilizzo avviene tramite una richiesta POST:
POST /v1/billing/teams/{teamId}/usage
Struttura della richiesta
{
"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"]
}
}
Questa richiesta chiede la somma dei token consumati al giorno, suddivisi per modello, per marzo 2026 in UTC. Considerala un modello: nella pratica, da un report all’altro cambierai solo tre elementi: il periodo, l’unità di tempo e la metrica, mentre il resto della struttura rimane identico.
Parametri della richiesta
timeRange
Definisce il periodo di analisi:
- startTime: inizio del periodo (formato
YYYY-MM-DD HH:MM:SS) - endTime: fine del periodo (stesso formato)
- timezone: fuso orario per l’interpretazione delle date (es.
UTC,Europe/Paris)
timeUnit
La granularità temporale dei risultati. Le opzioni disponibili sono:
- MONTH: aggregazione mensile
- CALENDAR_WEEK: aggregazione per settimana di calendario
- DAY: aggregazione giornaliera
- HOUR: aggregazione oraria
- QUARTER_HOUR: aggregazione per quarto d’ora
- MINUTE: aggregazione al minuto
- SECOND: aggregazione al secondo
Scegli la granularità in base alla durata del fenomeno che stai cercando, non alla lunghezza del periodo analizzato. Un report mensile si legge bene in DAY; un picco di dieci minuti scompare completamente a quella scala e appare solo in QUARTER_HOUR. Scendere troppo in basso ha comunque un costo: il volume dei punti restituiti cresce rapidamente, così come il rumore di fondo.
values
La scelta della funzione di aggregazione cambia la domanda posta, ed è qui che i percentili meritano la tua attenzione. AVG sulla latenza fornisce una media rassicurante che nessuno sperimenta realmente; P99 indica il tempo di attesa subito dai tuoi utenti più sfortunati, quelli che si lamentano. Per i costi, usa SUM; per le prestazioni, usa un percentile.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Funzioni di aggregazione disponibili:
- SUM: somma totale
- AVG: media
- MIN: valore minimo
- MAX: valore massimo
- P50: mediana (50° percentile)
- P90: 90° percentile
- P99: 99° percentile
- COUNT: numero di occorrenze
- COUNT_DISTINCT: numero di valori distinti
groupBy
Suddivide i risultati per dimensione. Attualmente, il raggruppamento per model è disponibile, permettendoti di vedere il consumo separato per ogni modello (grok-4.20-0309-reasoning, grok-4.3, ecc.).
Esempi pratici
Consumo giornaliero per il mese corrente
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"]
}
}'
Numero di richieste per ora
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"]
}
}'
Latenza P99 per modello
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"]
}
}'
Punti chiave
- L’endpoint
POST /v1/billing/teams/{teamId}/usagecentralizza tutte le analisi - 7 granularità temporali disponibili, da SECOND a MONTH
- 9 funzioni di aggregazione: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Il parametro
groupBy: ["model"]suddivide i risultati per modello - Usa il fuso orario
Europe/Parisper i report allineati ai tuoi orari di lavoro