Analytika využívania
Na tejto strane
Pochopte svoju spotrebu API
Faktúra ti povie, koľko si minul; tento koncový bod ti prezradí prečo. V tom je rozdiel medzi pasívnym sledovaním a aktívnym konaním: spotreba sa rozkladá podľa modelu, obdobia a zvolenej granularity, čo ti umožňuje prepojiť náhly nárast s konkrétnym modelom v konkrétnom čase.
Jeho syntax je bohatšia než u zvyšku Management API – kombinuješ tri bloky parametrov –, ale v konečnom dôsledku ide odpovedať na tri otázky: za aké obdobie, s akou granularitou a akú mieru sledovať. Táto lekcia ich pokrýva presne v tomto poradí. Umožňuje ti analyzovať spotrebu podľa modelu, podľa obdobia a s rôznymi časovými granularitami – čo sú zásadné údaje pre optimalizáciu nákladov a plánovanie kapacity tvojej infraštruktúry.
Koncový bod pre analýzu
Analýza využívania prebieha prostredníctvom požiadavky POST:
POST /v1/billing/teams/{teamId}/usage
Štruktúra požiadavky
{
"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"]
}
}
Táto požiadavka žiada o súčet spotrebovaných tokenov za deň, rozdelený podľa modelu, pre marec 2026 v časovom pásme UTC. Ber to ako šablónu: v praxi budeš od jedného reportu k druhému meniť len tri veci – obdobie, časovú jednotku a metriku –, zatiaľ čo zvyšok štruktúry zostane identický.
Parametre požiadavky
timeRange
Definuje obdobie analýzy:
- startTime : začiatok obdobia (formát
YYYY-MM-DD HH:MM:SS) - endTime : koniec obdobia (rovnaký formát)
- timezone : časové pásmo pre interpretáciu dátumov (napr.
UTC,Europe/Paris)
timeUnit
Časová granularita výsledkov. K dispozícii sú tieto možnosti:
- MONTH : mesačná agregácia
- CALENDAR_WEEK : agregácia podľa kalendárneho týždňa
- DAY : denná agregácia
- HOUR : hodinová agregácia
- QUARTER_HOUR : agregácia po štvrťhodinách
- MINUTE : minútová agregácia
- SECOND : sekundová agregácia
Granularitu vyberaj podľa dĺžky trvania javu, ktorý hľadáš, nie podľa dĺžky analyzovaného obdobia. Mesačný report sa dobre číta v DAY; desaťminútový výkyv pri tejto škále úplne zmizne a objaví sa až v QUARTER_HOUR. Príliš nízka granularita má však svoju cenu – objem vrátených dátových bodov rýchlo rastie a spolu s ním aj šum.
values
Výber agregačnej funkcie mení položenú otázku a práve tu si zaslúžia percentily tvoju pozornosť. AVG pri latencii poskytuje upokojujúci priemer, ktorý v skutočnosti nikto nezažíva; P99 udáva čas čakania, ktorý znášajú tvoji najmenej šťastní používatelia – tí, ktorí sa sťažujú. Pre náklady používaj SUM; pre výkon používaj percentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Dostupné agregačné funkcie:
- SUM : celkový súčet
- AVG : priemer
- MIN : minimálna hodnota
- MAX : maximálna hodnota
- P50 : medián (50. percentil)
- P90 : 90. percentil
- P99 : 99. percentil
- COUNT : počet výskytov
- COUNT_DISTINCT : počet distinct hodnôt
groupBy
Rozdeľuje výsledky podľa dimenzie. V súčasnosti je dostupné zoskupenie podľa model, čo ti umožňuje vidieť samostatnú spotrebu pre každý model (grok-4.20-0309-reasoning, grok-4.3 atď.).
Praktické príklady
Denná spotreba za aktuálny mesiac
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"]
}
}'
Počet požiadaviek za hodinu
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"]
}
}'
Latencia P99 podľa 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"]
}
}'
Kľúčové poznatky
- Koncový bod
POST /v1/billing/teams/{teamId}/usagecentralizuje všetku analytiku - K dispozícii je 7 časových granularít, od SECOND po MONTH
- 9 agregačných funkcií: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parameter
groupBy: ["model"]rozdeľuje výsledky podľa modelu - Pre reporty zosúladené s tvojím pracovným časom používaj časové pásmo
Europe/Paris