Analitika naudojimo
Šiame puslapyje
Suprask savo API vartojimą
Sąskaita faktūra nurodo, kiek išleidai; šis galinis taškas paaiškina kodėl. Tai skirtumas tarp stebėjimo ir veiksmo: vartojimas suskirstomas pagal modelį, laikotarpį ir tavo pasirinktą granuliariumą, leidžiantis susieti šuolį su konkrečiu modelu konkrečiu laiku.
Jo sintaksė turtingesnė nei kitų Valdymo API dalių – trys parametrų blokai derinimui, – tačiau viskas susiveda į tris klausimus: kokiu laikotarpiu, kokiu granuliariumu ir koks matas. Šioje pamokoje juos nagrinėsime būtent tokia tvarka. Tai leidžia analizuoti vartojimą pagal modelį, laikotarpį ir skirtingus laiko granuliariumus – esminius duomenis kaštams optimizuoti ir infrastruktūrai parinkti.
Analizės galinis taškas
Naudojimo analizė atliekama naudojant POST užklausą:
POST /v1/billing/teams/{teamId}/usage
Užklausos struktūra
{
"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"]
}
}
Ši užklausa prašo bendros sunaudotų tokenų sumos per dieną, suskirstytos pagal modelį, 2026 m. kovą UTC laiku. Laikyk tai šablonu: praktiškai iš vienos ataskaitos į kitą keisi tik tris dalykus – laikotarpį, laiko vienetą ir metriką, – o likusi struktūra lieka identiška.
Užklausos parametrai
timeRange
Apibrėžia analizės laikotarpį:
- startTime : laikotarpio pradžia (formatas
YYYY-MM-DD HH:MM:SS) - endTime : laikotarpio pabaiga (tas pats formatas)
- timezone : laiko juosta datų interpretavimui (pvz.,
UTC,Europe/Paris)
timeUnit
Rezultatų laiko granuliariumas. Galimi variantai:
- MONTH : mėnesio agregacija
- CALENDAR_WEEK : kalendorinės savaitės agregacija
- DAY : dienos agregacija
- HOUR : valandos agregacija
- QUARTER_HOUR : ketvirčio valandos agregacija
- MINUTE : minutės agregacija
- SECOND : sekundės agregacija
Granuliariumą rinkis pagal tiriamo reiškinio trukmę, o ne pagal analizuojamo laikotarpio ilgį. Mėnesio ataskaita gerai skaitoma naudojant DAY; dešimties minučių šuolis tokiu masteliu visiškai išnyksta ir pasimato tik naudojant QUARTER_HOUR. Per didelis smulkmeningumas taip pat turi kainą – grąžinamų taškų apimtis greitai auga, o kartu didėja ir triukšmas.
values
Agregacijos funkcijos pasirinkimas keičia užduodamą klausimą, ir būtent čia percentiliai nusipelno tavo dėmesio. AVG latencijai suteikia raminantį vidurkį, kurio niekas realiai nepatiria; P99 rodo laukimo laiką, kurį patyrė nesėkmingiausi naudotojai – tie, kurie skundžiasi. Kaštams naudok SUM; našumui – percentilį.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Galimos agregacijos funkcijos:
- SUM : bendra suma
- AVG : vidurkis
- MIN : mažiausia reikšmė
- MAX : didžiausia reikšmė
- P50 : mediana (50-asis percentilis)
- P90 : 90-asis percentilis
- P99 : 99-asis percentilis
- COUNT : įvykių skaičius
- COUNT_DISTINCT : unikalių reikšmių skaičius
groupBy
Suskirsto rezultatus pagal dimensiją. Šiuo metu galima grupuoti pagal model, leidžiant matyti atskirą kiekvieno modelio vartojimą (grok-4.20-0309-reasoning, grok-4.3 ir kt.).
Praktiniai pavyzdžiai
Dienos vartojimas einamajam mėnesiui
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"]
}
}'
Užklausų skaičius per valandą
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 pagal modelį
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"]
}
}'
Svarbiausi punktai
- Galinis taškas
POST /v1/billing/teams/{teamId}/usagecentralizuoja visą analitiką - Yra 7 laiko granuliariumai: nuo SECOND iki MONTH
- 9 agregacijos funkcijos: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parametras
groupBy: ["model"]suskirsto rezultatus pagal modelį - Ataskaitoms, suderintoms su tavo darbo laiku, naudok laiko juostą
Europe/Paris