Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Analytika využívání

Lekce 9 z 14 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Pochopte svou spotřebu API
  2. Koncový bod pro analýzu
  3. Parametry požadavku
  4. Praktické příklady
  5. Klíčové poznatky

Pochopte svou spotřebu API

Dashboard využívání v konzoli xAI 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.

7
Časové jednotky
9
Agregace
POST
Metoda HTTP
groupBy
Rozdělení podle modelu

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}/usage centralizuje 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