Analiżi tal-Użu
F'din il-paġna
Fhem il-Konsum tal-API Tiegħek
Fattura tgħidlek kemm nefqt; dan l-endpoint jgħidlek għaliex. Dik hija d-differenza bejn l-osservazzjoni u l-azzjoni: il-konsum jinqasam skont il-mudell, skont il-perjodu, u bil-granularità li tagħżel int, u jħallik torbot żieda f’daqqa ma’ mudell speċifiku f’ħin speċifiku.
Is-sintassi tiegħu hija aktar rikka mill-bqija tal-API tal-Ġestjoni—tliet blokok ta’ parametri biex tgħaqqad—imma tinżel għal tliet mistoqsijiet: fuq liema perjodu, b’liema granularità, u liema kejl. Din il-lezzjoni tkoprihom f’dak l-ordni. Tippermettilek tanalizza l-konsum skont il-mudell, skont il-perjodu, u b’granularitajiet temporali differenti—data essenzjali biex tottimizza l-ispejjeż u tiddimensjona l-infrastruttura tiegħek.
Endpoint tal-Analiżi
L-analiżi tal-użu issir permezz ta’ talba POST:
POST /v1/billing/teams/{teamId}/usage
Struttura tat-Talba
{
"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"]
}
}
Din it-talba titlob is-somma tat-tokens ikkunsmati kuljum, maqsuma skont il-mudell, għal Marzu 2026 fi UTC. Ikkunsidraha bħala mudell: fil-prattika, minn rapport għall-ieħor tibdel biss tliet affarijiet—il-perjodu, l-unità ta’ ħin, u l-metrika—filwaqt li l-bqija tal-istruttura tibqa’ identika.
Parametri tat-Talba
timeRange
Jiddefinixxi l-perjodu tal-analiżi:
- startTime : bidu tal-perjodu (format
YYYY-MM-DD HH:MM:SS) - endTime : tmiem tal-perjodu (l-istess format)
- timezone : iż-żona tal-ħin għall-interpretazzjoni tad-data (eż.
UTC,Europe/Paris)
timeUnit
Il-granularità temporali tar-riżultati. L-għażliet disponibbli huma:
- MONTH : aggregazzjoni ta’ kull xahar
- CALENDAR_WEEK : aggregazzjoni ta’ kull ġimgħa kalendarja
- DAY : aggregazzjoni ta’ kuljum
- HOUR : aggregazzjoni ta’ kull siegħa
- QUARTER_HOUR : aggregazzjoni ta’ kull kwart ta’ siegħa
- MINUTE : aggregazzjoni ta’ kull minuta
- SECOND : aggregazzjoni ta’ kull sekonda
Agħżel il-granularità abbażi tad-durata tal-fenomenu li qed tfittex, mhux it-tul tal-perjodu analizzat. Rapport ta’ kull xahar jinqara tajjeb b’DAY; żieda f’daqqa ta’ għaxar minuti tisparixxi kompletament f’dik l-iskala u tidher biss b’QUARTER_HOUR. Li tmur baxx wisq għandu spiża wkoll—il-volum ta’ punti rritornati jikber malajr, u hekk ukoll in-niżla.
values
L-għażla tal-funzjoni ta’ aggregazzjoni tbiddel il-mistoqsija magħmula, u hawnhekk il-perċentili jisħqu l-attenzjoni tiegħek. AVG fuq il-latency jagħti medja li tikkalma li ħadd fil-fatt ma jesperjenza; P99 jagħti l-ħin ta’ stennija li ġarrbu l-utenti l-aktar sfortunati tiegħek—dawk li jilmentaw. Għall-ispiża, uża SUM; għall-prestazzjoni, uża perċentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Funzjonijiet ta’ aggregazzjoni disponibbli:
- SUM : somma totali
- AVG : medja
- MIN : valur minimu
- MAX : valur massimu
- P50 : medjana (il-50 perċentil)
- P90 : id-90 perċentil
- P99 : id-99 perċentil
- COUNT : numru ta’ okkorrenzi
- COUNT_DISTINCT : numru ta’ valuri distinti
groupBy
Jaqsam ir-riżultati skont id-dimensjoni. Attwalment, il-ħolqien ta’ gruppi skont model huwa disponibbli, u jħallik tara l-konsum separat għal kull mudell (grok-4.20-0309-reasoning, grok-4.3, eċċ.).
Eżempji Prattiċi
Konsum ta’ Kuljum għax-Xahar Attwali
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"]
}
}'
Numru ta’ Talbiet kull Siegħa
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"]
}
}'
Latenza P99 skont il-Mudell
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"]
}
}'
Punti Ewlenin
- L-endpoint
POST /v1/billing/teams/{teamId}/usagejiċċentralizza l-analiżi kollha - 7 granularitajiet ta’ ħin disponibbli, minn SECOND sa MONTH
- 9 funzjonijiet ta’ aggregazzjoni: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Il-parametru
groupBy: ["model"]jaqsam ir-riżultati skont il-mudell - Uża ż-żona tal-ħin
Europe/Parisgħal rapporti allinjati mas-sigħat tax-xogħol tiegħek