Kasutusanalüütika
Sellel lehel
Mõista oma API tarbimist
Arve ütleb sulle, kui palju sa kulutasid; see lõpp-punkt selgitab, miks. Selles seisnebki erinevus vaatlemise ja tegutsemise vahel: tarbimine jaotub mudelite kaupa, ajaperiooditi ja sinu valitud detailsusega, võimaldades seostada tarbimisharju kindla mudeliga kindlal ajal.
Selle süntaks on rikkalikum kui ülejäänud haldus-API-l – kolm parameetrite plokki, mida kombineerida –, kuid taandub lõpuks kolmele küsimusele: millise perioodi üle, millise detailsusega ja millist mõõdikut kasutades. See õppetund käsitleb neid just selles järjekorras. See võimaldab analüüsida tarbimist mudelite kaupa, ajaperiooditi ja erineva ajalise detailsusega – hädavajalikud andmed kulude optimeerimiseks ja infrastruktuuri planeerimiseks.
Analüüsi lõpp-punkt
Kasutuse analüüs toimub POST päringu kaudu:
POST /v1/billing/teams/{teamId}/usage
Päringu struktuur
{
"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"]
}
}
See päring küsib märtsis 2026 (UTC ajavööndis) tarbitud tokenite summat päeva kaupa, jaotatuna mudelite lõikes. Vaata seda kui malli: praktikas muudad sa ühest aruandest teise liikudes vaid kolme asja – perioodi, ajaühikut ja mõõdikut –, samas kui ülejäänud struktuur jääb identseks.
Päringu parameetrid
timeRange
Määratleb analüüsi perioodi:
- startTime : perioodi algus (formaadis
YYYY-MM-DD HH:MM:SS) - endTime : perioodi lõpp (sama formaat)
- timezone : ajavöönd kuupäevade tõlgendamiseks (nt
UTC,Europe/Paris)
timeUnit
Tulemuste ajaline detailsus. Saadaval on järgmised valikud:
- MONTH : igakuine agregeerimine
- CALENDAR_WEEK : kalendrinädala agregeerimine
- DAY : igapäevane agregeerimine
- HOUR : tunnine agregeerimine
- QUARTER_HOUR : veerandtunnine agregeerimine
- MINUTE : minutine agregeerimine
- SECOND : sekundiline agregeerimine
Vali detailsus vastavalt selle nähtuse kestusele, mida otsid, mitte analüüsitava perioodi pikkusele. Igakuine aruanne loeb hästi DAY detailsusega; kümne minuti pikkune tarbimishari kaob selles mastaabis täielikult ja tuleb esile vaid QUARTER_HOUR puhul. Liiga madala taseme valimisel on samuti hind – tagastatud andmepunktide maht kasvab kiiresti ja sellega koos ka müra.
values
Agregeerimisfunktsiooni valik muudab esitatavat küsimust ja just siin väärivad protsentiilid sinu tähelepanu. AVG latentsusel annab rahustava keskmise, mida tegelikult keegi ei koge; P99 annab ooteaja, mida kogevad sinu ebaõnnelikumad kasutajad – need, kes kaebavad. Kulude jaoks kasuta SUM; jõudluse jaoks kasuta protsentiili.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Saadaval olevad agregeerimisfunktsioonid:
- SUM : kogusumma
- AVG : keskmine
- MIN : minimaalne väärtus
- MAX : maksimaalne väärtus
- P50 : mediaan (50. protsentiil)
- P90 : 90. protsentiil
- P99 : 99. protsentiil
- COUNT : esinemiste arv
- COUNT_DISTINCT : erinevate väärtuste arv
groupBy
Jaotab tulemused mõõtme järgi. Praegu on saadaval rühmitamine model järgi, mis võimaldab näha iga mudeli (grok-4.20-0309-reasoning, grok-4.3 jne) tarbimist eraldi.
Praktilised näited
Igapäevane tarbimine jooksvaks kuuks
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"]
}
}'
Päringute arv tunni kaupa
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 latentsus mudelite kaupa
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"]
}
}'
Peamised punktid
- Lõpp-punkt
POST /v1/billing/teams/{teamId}/usagekoondab kogu analüütika - Saadaval on 7 ajalist detailsust, alates
SECONDkuniMONTH - 9 agregeerimisfunktsiooni: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parameeter
groupBy: ["model"]jaotab tulemused mudelite kaupa - Kasuta ajavööndit
Europe/Parisaruannete jaoks, mis on joondatud sinu tööajaga