Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Analisi dell'utilizzo

Lezione 9 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Comprendi il tuo consumo API
  2. Endpoint di analisi
  3. Parametri della richiesta
  4. Esempi pratici
  5. Punti chiave

Comprendi il tuo consumo API

Dashboard di utilizzo nella console xAI 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.

7
Unità di tempo
9
Aggregazioni
POST
Metodo HTTP
groupBy
Suddivisione per modello

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}/usage centralizza 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/Paris per i report allineati ai tuoi orari di lavoro