Analitika uporabe
Na tej strani
Razumevanje porabe API-ja
Račun ti pove, koliko si porabil; ta končna točka ti pove zakaj. To je razlika med opazovanjem in ukrepanjem: poraba se razčleni po modelu, po obdobju in po izbrani granularnosti, kar ti omogoča, da skok povežeš z določenim modelom ob določenem času.
Njegova sintaksa je bogatejša od preostanka upravljalnega API-ja – trije bloki parametrov za kombiniranje – vendar se vse skrči na tri vprašanja: v kakšnem obdobju, s kakšno granularnostjo in kakšen ukrep. Ta lekcija jih obravnava v tem vrstnem redu. Omogoča ti analizo porabe po modelu, po obdobju in z različnimi časovnimi granularnostmi – bistveni podatki za optimizacijo stroškov in načrtovanje tvoje infrastrukture.
Končna točka za analizo
Analiza uporabe poteka prek zahteve POST:
POST /v1/billing/teams/{teamId}/usage
Struktura zahteve
{
"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"]
}
}
Ta zahteva zahteva vsoto porabljenih žetonov na dan, razčlenjeno po modelu, za marec 2026 v času UTC. Obravnavaj jo kot predlogo: v praksi boš od poročila do poročila spremenil le tri stvari – obdobje, časovno enoto in metrike –, medtem ko bo preostala struktura ostala enaka.
Parametri zahteve
timeRange
Določa obdobje analize:
- startTime : začetek obdobja (oblika
YYYY-MM-DD HH:MM:SS) - endTime : konec obdobja (ista oblika)
- timezone : časovni pas za razlago datumov (npr.
UTC,Europe/Paris)
timeUnit
Časovna granularnost rezultatov. Na voljo so naslednje možnosti:
- MONTH : mesečna agregacija
- CALENDAR_WEEK : agregacija po koledarskem tednu
- DAY : dnevna agregacija
- HOUR : urna agregacija
- QUARTER_HOUR : agregacija po četrturah
- MINUTE : minutna agregacija
- SECOND : sekundna agregacija
Granularnost izberi glede na trajanje pojava, ki ga iščeš, ne glede na dolžino analiziranega obdobja. Mesečno poročilo je berljivo v DAY; desetminutni skok pri tej lestvici popolnoma izgine in se pokaže le v QUARTER_HOUR. Prevelika podrobnost ima tudi svojo ceno – količina vrnjenih točk hitro naraste, prav tako pa tudi šum.
values
Izbira funkcije agregacije spremeni zastavljeno vprašanje, pri čemer si percentili zaslužijo tvojo pozornost. AVG pri zakasnitvi (latency) poda pomirjujoče povprečje, ki ga v resnici ne doživi nihče; P99 poda čas čakanja, ki ga trpijo tvoji najmanj srečni uporabniki – tisti, ki se pritožujejo. Za stroške uporabi SUM; za zmogljivost uporabi percentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Razpoložljive funkcije agregacije:
- SUM : skupna vsota
- AVG : povprečje
- MIN : najmanjša vrednost
- MAX : največja vrednost
- P50 : mediana (50. percentil)
- P90 : 90. percentil
- P99 : 99. percentil
- COUNT : število pojavitev
- COUNT_DISTINCT : število različnih vrednosti
groupBy
Rezultate razčleni po dimenziji. Trenutno je na voljo grupiranje po model, kar ti omogoča, da vidiš ločeno porabo za vsak model (grok-4.20-0309-reasoning, grok-4.3 itd.).
Praktični primeri
Dnevna poraba za tekoči mesec
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"]
}
}'
Število zahtev na uro
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"]
}
}'
Zakasnitev P99 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 ugotovitve
- Končna točka
POST /v1/billing/teams/{teamId}/usagezdružuje vso analitiko - Na voljo je 7 časovnih granularnosti, od SECOND do MONTH
- 9 funkcij agregacije: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parameter
groupBy: ["model"]razčleni rezultate po modelu - Za poročila, usklajena s tvojim delovnim časom, uporabi časovni pas
Europe/Paris