Käyttöanalytiikka
Tällä sivulla
Ymmärrä API-kulutuksesi
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.
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