Használati elemzések
Ezen az oldalon
Értsd meg az API-fogyasztásodat
A számla megmutatja, mennyit költöttél; ez a végpont pedig azt árulja el, miért. Ez a különbség a puszta megfigyelés és a cselekvés között: a fogyasztás lebontható modell szerint, időszakra vonatkozóan és az általad választott részletességgel, így egy konkrét modellhez és időponthoz köthetsz egy kiugrást.
A szintaxisa gazdagabb, mint a Management API többi részéé – három paraméterblokkot kell kombinálnod –, de lényegében három kérdésre vezethető vissza: milyen időszakról, milyen részletességgel és milyen mérőszám alapján? Ez a lecke ezt a sorrendet követi. Lehetővé teszi a fogyasztás elemzését modellenként, időszakonként és különböző időbeli granularity-val – elengedhetetlen adat a költségek optimalizálásához és az infrastruktúra méretezéséhez.
Elemzési végpont
A használati elemzés egy POST kéréssel történik:
POST /v1/billing/teams/{teamId}/usage
Kérés szerkezete
{
"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"]
}
}
Ez a kérés a 2026. márciusi, UTC időzónában mért, modellenként lebontott napi tokenfogyasztás összegét kéri le. Tekints erre sablonként: a gyakorlatban egyik jelentésről a másikra csak három dolgot módosítasz – az időszakot, az időegységet és a mérőszámot –, míg a szerkezet többi része változatlan marad.
Kérési paraméterek
timeRange
Meghatározza az elemzés időszakát:
- startTime : az időszak kezdete (
YYYY-MM-DD HH:MM:SSformátum) - endTime : az időszak vége (ugyanolyan formátum)
- timezone : a dátumok értelmezéséhez használt időzóna (pl.
UTC,Europe/Paris)
timeUnit
Az eredmények időbeli részletessége. Elérhető lehetőségek:
- MONTH : havi aggregáció
- CALENDAR_WEEK : naptári heti aggregáció
- DAY : napi aggregáció
- HOUR : óránkénti aggregáció
- QUARTER_HOUR : negyedóránkénti aggregáció
- MINUTE : percenkénti aggregáció
- SECOND : másodpercenkénti aggregáció
A részletességet a keresett jelenség időtartama alapján válaszd meg, nem pedig az elemzett időszak hossza alapján. Egy havi jelentés jól olvasható DAY részletességgel; egy tízperces kiugrás ezen a skálán teljesen eltűnik, és csak QUARTER_HOUR esetén válik láthatóvá. A túl alacsony szintű választásnak is van ára: a visszaadott adatpontok száma gyorsan nő, és vele együtt a zaj is.
values
Az aggregációs függvény megválasztása megváltoztatja a feltett kérdést, és itt érdemes odafigyelned a percentilisekre. A késleltetésre (latency) számított AVG egy megnyugtató átlagot ad, amit a valóságban senki sem tapasztal; a P99 viszont azt a várakozási időt mutatja, amit a legszerencsétlenebb felhasználóid – azok, akik panaszkodnak – elszenvednek. Költségekhez használd a SUM-ot, teljesítményelemzéshez pedig egy percentilist.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Elérhető aggregációs függvények:
- SUM : teljes összeg
- AVG : átlag
- MIN : minimum érték
- MAX : maximum érték
- P50 : medián (50. percentilis)
- P90 : 90. percentilis
- P99 : 99. percentilis
- COUNT : előfordulások száma
- COUNT_DISTINCT : egyedi értékek száma
groupBy
Dimenziók szerinti lebontást tesz lehetővé. Jelenleg a model szerinti csoportosítás elérhető, így minden modell (pl. grok-4.20-0309-reasoning, grok-4.3) fogyasztása külön-külön látható.
Gyakorlati példák
Napi fogyasztás az aktuális hónapban
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"]
}
}'
Kérések száma óránként
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 késleltetés modellenként
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"]
}
}'
Főbb megállapítások
- A
POST /v1/billing/teams/{teamId}/usagevégpont centralizálja az összes elemzést - 7 elérhető időbeli részletesség, a
SECOND-tól aMONTH-ig - 9 aggregációs függvény: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- A
groupBy: ["model"]paraméter modellenként bontja le az eredményeket - Használd az
Europe/Parisidőzónát a munkaidődhöz igazított jelentésekhez