Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Kasutusanalüütika

Õppetund 9 / 14 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Mõista oma API tarbimist
  2. Analüüsi lõpp-punkt
  3. Päringu parameetrid
  4. Praktilised näited
  5. Peamised punktid

Mõista oma API tarbimist

Kasutuse armatuurlaud xAI konsoolis 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.

7
Ajaühikud
9
Agregeerimised
POST
HTTP meetod
groupBy
Jaotus mudelite kaupa

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}/usage koondab kogu analüütika
  • Saadaval on 7 ajalist detailsust, alates SECOND kuni MONTH
  • 9 agregeerimisfunktsiooni: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
  • Parameeter groupBy: ["model"] jaotab tulemused mudelite kaupa
  • Kasuta ajavööndit Europe/Paris aruannete jaoks, mis on joondatud sinu tööajaga