Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Käyttöanalytiikka

Oppitunti 9 / 14 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Ymmärrä API-kulutuksesi
  2. Analyysipäätepiste
  3. Pyynnön parametrit
  4. Käytännön esimerkkejä
  5. Keskeiset asiat

Ymmärrä API-kulutuksesi

Käyttötilannekuva xAI-konsolissa Lasku kertoo, kuinka paljon olet käyttänyt rahaa; tämä päätepiste kertoo miksi. Siinä on ero havainnoimisen ja toimimisen välillä: kulutus eritellään malleittain, aikajaksoittain ja valitsemallasi tarkkuudella, joten voit yhdistää piikin tiettyyn malliin tiettynä aikana.

Sen syntaksi on rikkaampi kuin muulla Hallinta-API:lla – kolme yhdistettävää parametrilohkoa – mutta se tiivistyy kolmeen kysymykseen: miltä ajalta, millä tarkkuudella ja mitä mittaria mitataan. Tämä oppitunti käsittelee niitä tässä järjestyksessä. Sen avulla voit analysoida kulutusta malleittain, aikajaksoittain ja eri aikataajuuksilla – nämä tiedot ovat välttämättömiä kustannusten optimoinnille ja infrastruktuurisi mitoittamiselle.

7
Aikayksiköt
9
Aggregoinnit
POST
HTTP-metodi
groupBy
Erittely malleittain

Analyysipäätepiste

Käyttöanalyysi suoritetaan POST-pyynnöllä:

POST /v1/billing/teams/{teamId}/usage

Pyynnön rakenne

{
  "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ämä pyyntö hakee päivittäisen token-kulutuksen summan eriteltynä malleittain maaliskuulle 2026 UTC-ajassa. Käytä tätä pohjana: käytännössä muutat raportista toiseen vain kolmea asiaa – aikaväliä, aikayksikköä ja mittaria – kun taas loput rakenteesta pysyvät samoina.

Pyynnön parametrit

timeRange

Määrittää analysoitavan aikavälin:

  • startTime : jakson alku (muoto YYYY-MM-DD HH:MM:SS)
  • endTime : jakson loppu (sama muoto)
  • timezone : aikavyöhyke päivämäärien tulkintaa varten (esim. UTC, Europe/Paris)

timeUnit

Tulosten aikataajuus. Käytettävissä olevat vaihtoehdot ovat:

  • MONTH : kuukausittainen aggregointi
  • CALENDAR_WEEK : kalenteriviikon aggregointi
  • DAY : päivittäinen aggregointi
  • HOUR : tuntikohtainen aggregointi
  • QUARTER_HOUR : neljännesvarttitunnin aggregointi
  • MINUTE : minuuttikohtainen aggregointi
  • SECOND : sekuntikohtainen aggregointi

Valitse tarkkuus sen ilmiön keston perusteella, jota etsit, äläkä analysoidun jakson pituuden perusteella. Kuukausiraportti on luettavissa parhaiten DAY-tarkkuudella; kymmenen minuutin piikki katoaa tässä mittakaavassa kokonaan ja näkyy vain QUARTER_HOUR-tarkkuudella. Liian pienellä tarkkuudella on myös hintansa: palautettujen datapisteiden määrä kasvaa nopeasti, samoin kuin kohina.

values

Aggregointifunktion valinta muuttaa kysymyksen luonnetta, ja juuri tässä prosenttipisteet ansaitsevat huomiosi. Latenssin AVG antaa lohduttavan keskiarvon, jota kukaan ei todellisuudessa koe; P99 antaa odotusajan, jonka kaikkein epäonnisimmat käyttäjäsi – ne, jotka valittavat – joutuvat kestämään. Käytä kustannuksille SUM:ia ja suorituskyvylle prosenttipistettä.

"values": [
  {"name": "tokens", "aggregation": "SUM"},
  {"name": "tokens", "aggregation": "AVG"},
  {"name": "latency", "aggregation": "P99"}
]

Käytettävissä olevat aggregointifunktiot:

  • SUM : kokonaissumma
  • AVG : keskiarvo
  • MIN : pienin arvo
  • MAX : suurin arvo
  • P50 : mediaani (50. prosenttipiste)
  • P90 : 90. prosenttipiste
  • P99 : 99. prosenttipiste
  • COUNT : esiintymiskertojen lukumäärä
  • COUNT_DISTINCT : erillisten arvojen lukumäärä

groupBy

Erottelee tulokset ulottuvuuden mukaan. Tällä hetkellä ryhmittely model-parametrilla on käytettävissä, jolloin näet kulutuksen erikseen jokaiselle mallille (grok-4.20-0309-reasoning, grok-4.3 jne.).

Käytännön esimerkkejä

Päivittäinen kulutus kuluvana kuukautena

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"]
    }
  }'

Pyyntöjen määrä tunnissa

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-latenssi malleittain

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"]
    }
  }'

Keskeiset asiat

  • POST /v1/billing/teams/{teamId}/usage -päätepiste kokoaa kaiken analytiikan
  • 7 saatavilla olevaa aikataajuutta SECONDista MONTHiin
  • 9 aggregointifunktiota: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
  • groupBy: ["model"] -parametri erittelee tulokset malleittain
  • Käytä Europe/Paris-aikavyöhykettä raportteihin, jotka on linjattu työaikojesi kanssa