Analytika využívání
Na této stránce
Pochopte svou spotřebu API
Faktura ti řekne, kolik jsi utratil; tento koncový bod ti prozradí proč. V tom je rozdíl mezi pouhým pozorováním a aktivním jednáním: spotřeba se rozkládá podle modelu, podle období a podle vámi zvolené granularity, což ti umožňuje spojit náhlý nárůst s konkrétním modelem v konkrétním čase.
Jeho syntaxe je bohatší než u zbytku Management API – kombinuješ tři bloky parametrů –, ale v podstatě se vše točí kolem tří otázek: za jaké období, s jakou granularitou a jakou metriku měříš. Tato lekce je probírá právě v tomto pořadí. Umožňuje ti analyzovat spotřebu podle modelu, podle období a s různou časovou granularitou – což jsou zásadní data pro optimalizaci nákladů a plánování kapacity tvé infrastruktury.
Koncový bod pro analýzu
Analýza využívání probíhá prostřednictvím požadavku POST:
POST /v1/billing/teams/{teamId}/usage
Struktura požadavku
{
"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"]
}
}
Tento požadavek žádá o součet spotřebovaných tokenů za den s rozdělením podle modelu pro březen 2026 v časovém pásmu UTC. Ber to jako šablonu: v praxi budeš od jednoho reportu k druhému měnit pouze tři věci – období, časovou jednotku a metriku –, zatímco zbytek struktury zůstane totožný.
Parametry požadavku
timeRange
Definuje období analýzy:
- startTime : začátek období (formát
YYYY-MM-DD HH:MM:SS) - endTime : konec období (stejný formát)
- timezone : časové pásmo pro interpretaci dat (např.
UTC,Europe/Paris)
timeUnit
Časová granularita výsledků. K dispozici jsou tyto možnosti:
- MONTH : měsíční agregace
- CALENDAR_WEEK : agregace podle kalendářního týdne
- DAY : denní agregace
- HOUR : hodinová agregace
- QUARTER_HOUR : agregace po čtvrt hodinách
- MINUTE : minutová agregace
- SECOND : sekundová agregace
Granularitu vybírej podle délky jevu, který hledáš, nikoliv podle délky analyzovaného období. Měsíční report se dobře čte v DAY; desetiminutový výkyv v této škále zcela zmizí a projeví se až v QUARTER_HOUR. Příliš nízká granularita má však také svou cenu – objem vrácených bodů rychle roste a s ním i šum.
values
Volba agregační funkce mění položenou otázku a právě zde si zaslouží tvou pozornost percentily. AVG u latence poskytuje uklidňující průměr, který ve skutečnosti nikdo nezažívá; P99 udává dobu čekání, kterou snášejí tvoji nejsmolnější uživatelé – ti, kteří si stěžují. Pro náklady použij SUM; pro výkon použij percentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Dostupné agregační funkce:
- SUM : celkový součet
- AVG : průměr
- MIN : minimální hodnota
- MAX : maximální hodnota
- P50 : medián (50. percentil)
- P90 : 90. percentil
- P99 : 99. percentil
- COUNT : počet výskytů
- COUNT_DISTINCT : počet distinct hodnot
groupBy
Rozděluje výsledky podle dimenze. V současnosti je dostupné seskupení podle model, což ti umožňuje vidět samostatnou spotřebu pro každý model (grok-4.20-0309-reasoning, grok-4.3 atd.).
Praktické příklady
Denní spotřeba za běžný měsíc
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žadavků 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"]
}
}'
Latence P99 podle 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"]
}
}'
Klíčové poznatky
- Koncový bod
POST /v1/billing/teams/{teamId}/usagecentralizuje veškerou analytiku - K dispozici je 7 časových granularit od SECOND po MONTH
- 9 agregačních funkcí: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parametr
groupBy: ["model"]rozděluje výsledky podle modelu - Pro reporty sladěné s tvou pracovní dobou použij časové pásmo
Europe/Paris