Analys av användning
På denna sida
Förstå din API-förbrukning
En faktura berättar hur mycket du har spenderat; denna endpoint berättar varför. Det är skillnaden mellan att observera och att agera: förbrukningen bryts ner per modell, per tidsperiod och med den granularitet du väljer, vilket låter dig koppla en topp till en specifik modell vid en specifik tidpunkt.
Syntaxen är rikare än för resten av Management API – tre block med parametrar att kombinera – men det kokar ner till tre frågor: under vilken period, med vilken granularitet och vilket mått? Denna lektion täcker dem i den ordningen. Den låter dig analysera förbrukning per modell, per period och med olika tidsupplösningar – avgörande data för att optimera kostnader och dimensionera din infrastruktur.
Analys-endpoint
Analys av användning sker via en POST-begäran:
POST /v1/billing/teams/{teamId}/usage
Begärans struktur
{
"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"]
}
}
Denna begäran frågar efter summan av förbrukade tokens per dag, uppdelat per modell, för mars 2026 i UTC. Behandla det som en mall: i praktiken ändrar du bara tre saker från en rapport till en annan – perioden, tidsenheten och metriket – medan resten av strukturen förblir identisk.
Begärans parametrar
timeRange
Definierar analysperioden:
- startTime : start på perioden (format
YYYY-MM-DD HH:MM:SS) - endTime : slut på perioden (samma format)
- timezone : tidszon för tolkning av datum (t.ex.
UTC,Europe/Paris)
timeUnit
Tidsupplösningen för resultaten. Tillgängliga alternativ är:
- MONTH : månadsvis aggregering
- CALENDAR_WEEK : aggregering per kalendervecka
- DAY : daglig aggregering
- HOUR : timvis aggregering
- QUARTER_HOUR : aggregering per kvart
- MINUTE : minutvis aggregering
- SECOND : sekundvis aggregering
Välj granularitet baserat på varaktigheten av det fenomen du letar efter, inte längden på den analyserade perioden. En månadsrapport läses bäst med DAY; en topp på tio minuter försvinner helt i den skalan och syns bara med QUARTER_HOUR. Att gå för lågt har också en kostnad – volymen returnerade datapunkter växer snabbt, liksom brusnivån.
values
Valet av aggregeringsfunktion ändrar frågan du ställer, och här är percentiler värda din uppmärksamhet. AVG på latens ger ett lugnande medelvärde som ingen faktiskt upplever; P99 ger väntetiden som dina mest oturssamma användare utsätts för – de som klagar. För kostnader använder du SUM; för prestanda använder du en percentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Tillgängliga aggregeringsfunktioner:
- SUM : total summa
- AVG : medelvärde
- MIN : lägsta värde
- MAX : högsta värde
- P50 : median (50:e percentilen)
- P90 : 90:e percentilen
- P99 : 99:e percentilen
- COUNT : antal förekomster
- COUNT_DISTINCT : antal distinkta värden
groupBy
Delar upp resultaten efter dimension. För närvarande är gruppering efter model tillgänglig, vilket låter dig se separat förbrukning för varje modell (grok-4.20-0309-reasoning, grok-4.3, etc.).
Praktiska exempel
Daglig förbrukning för innevarande månad
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"]
}
}'
Antal förfrågningar per timme
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-latens per modell
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"]
}
}'
Viktiga punkter
- Endpointen
POST /v1/billing/teams/{teamId}/usagecentraliserar all analys - 7 tidsupplösningar tillgängliga, från SECOND till MONTH
- 9 aggregeringsfunktioner: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parametern
groupBy: ["model"]delar upp resultaten per modell - Använd tidszonen
Europe/Parisför rapporter som är anpassade till dina arbetstider