Analitika korištenja
Na ovoj stranici
Razumijevanje potrošnje API-ja
Račun ti govori koliko si potrošio; ova krajnja točka objašnjava zašto. To je razlika između promatranja i djelovanja: potrošnja se raščlanjuje po modelu, po razdoblju i po odabranoj granulaciji, što ti omogućuje da povežeš skok potrošnje s određenim modelom u određenom trenutku.
Njegova je sintaksa bogatija od ostatka Management API-ja—tri bloka parametara za kombiniranje—ali svodi se na tri pitanja: tijekom kojeg razdoblja, s kojom granulacijom i koju mjeru? Ova lekcija obrađuje ih tim redoslijedom. Omogućuje ti analizu potrošnje po modelu, po razdoblju i s različitim vremenskim granulacijama—bitni podaci za optimizaciju troškova i dimenzioniranje tvoje infrastrukture.
Krajnja točka za analizu
Analiza korištenja odvija se putem POST zahtjeva:
POST /v1/billing/teams/{teamId}/usage
Struktura zahtjeva
{
"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"]
}
}
Ovaj zahtjev traži zbroj utrošenih tokena po danu, raščlanjeno po modelu, za ožujak 2026. u UTC vremenu. Tretiraj ga kao predložak: u praksi ćeš od jednog do drugog izvješća mijenjati samo tri stvari—razdoblje, vremensku jedinicu i metriku—dok ostatak strukture ostaje identičan.
Parametri zahtjeva
timeRange
Definira razdoblje analize:
- startTime : početak razdoblja (format
YYYY-MM-DD HH:MM:SS) - endTime : kraj razdoblja (isti format)
- timezone : vremenska zona za tumačenje datuma (npr.
UTC,Europe/Paris)
timeUnit
Vremenska granulacija rezultata. Dostupne opcije su:
- MONTH : mjesečna agregacija
- CALENDAR_WEEK : agregacija po kalendarskom tjednu
- DAY : dnevna agregacija
- HOUR : satna agregacija
- QUARTER_HOUR : agregacija po četvrtini sata
- MINUTE : minutna agregacija
- SECOND : sekundna agregacija
Odaberi granulaciju na temelju trajanja fenomena koji tražiš, a ne duljine analiziranog razdoblja. Mjesečno izvješće čitljivo je u DAY; desetominutni skok potpuno nestaje u toj razmjeri i vidljiv je samo u QUARTER_HOUR. Pretjerano fino podešavanje također ima svoju cijenu—volumina vraćenih točaka brzo raste, kao i šum.
values
Izbor funkcije agregacije mijenja postavljeno pitanje, a ovdje percentili zaslužuju tvoju pažnju. AVG na latenciji daje uvjerljivi prosjek koji nitko zapravo ne doživljava; P99 daje vrijeme čekanja koje trpe tvoji najnesretniji korisnici—oni koji se žale. Za troškove koristi SUM; za performanse koristi percentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Dostupne funkcije agregacije:
- SUM : ukupni zbroj
- AVG : prosjek
- MIN : minimalna vrijednost
- MAX : maksimalna vrijednost
- P50 : medijan (50. percentil)
- P90 : 90. percentil
- P99 : 99. percentil
- COUNT : broj pojavljivanja
- COUNT_DISTINCT : broj različitih vrijednosti
groupBy
Raščlanjuje rezultate po dimenziji. Trenutno je dostupno grupiranje po model, što ti omogućuje da vidiš zasebnu potrošnju za svaki model (grok-4.20-0309-reasoning, grok-4.3, itd.).
Praktični primjeri
Dnevna potrošnja za tekući mjesec
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"]
}
}'
Broj zahtjeva po satu
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"]
}
}'
P99 latencija po modelu
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"]
}
}'
Ključne točke
- Krajnja točka
POST /v1/billing/teams/{teamId}/usagecentralizira svu analitiku - Dostupno je 7 vremenskih granulacija, od SECOND do MONTH
- 9 funkcija agregacije: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parametar
groupBy: ["model"]raščlanjuje rezultate po modelu - Koristi vremensku zonu
Europe/Parisza izvješća usklađena s tvojim radnim vremenom