Brugsanalyser
På denne side
Forstå dit API-forbrug
En faktura fortæller dig, hvor meget du har brugt; dette endpoint fortæller dig hvorfor. Det er forskellen mellem at observere og at handle: Forbruget opdeles efter model, efter periode og med den granularitet, du vælger, så du kan kæde en top direkte til en specifik model på et bestemt tidspunkt.
Syntaksen er rigere end resten af Management API – tre blokke af parametre skal kombineres – men det koger ned til tre spørgsmål: Over hvilken periode, med hvilken granularitet og hvilket mål? Denne lektion dækker dem i den rækkefølge. Den lader dig analysere forbrug efter model, efter periode og med forskellige tidsmæssige opløsninger – essentielle data til at optimere omkostninger og dimensionere din infrastruktur.
Analyse-endpoint
Brugsanalysen foregår via en POST-forespørgsel:
POST /v1/billing/teams/{teamId}/usage
Forespørgselsstruktur
{
"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"]
}
}
Denne forespørgsel beder om summen af forbrugte tokens per dag, opdelt efter model, for marts 2026 i UTC. Betragt det som en skabelon: I praksis ændrer du kun tre ting fra rapport til rapport – perioden, tidsenheden og metrikken – mens resten af strukturen forbliver identisk.
Forespørgselsparametre
timeRange
Definerer analyseperioden:
- startTime : Start på perioden (format
YYYY-MM-DD HH:MM:SS) - endTime : Slut på perioden (samme format)
- timezone : Tidszone til fortolkning af datoer (f.eks.
UTC,Europe/Paris)
timeUnit
Resultaternes tidsmæssige granularitet. Tilgængelige muligheder er:
- MONTH : Månedlig aggregering
- CALENDAR_WEEK : Aggregering efter kalenderuge
- DAY : Daglig aggregering
- HOUR : Timevis aggregering
- QUARTER_HOUR : Aggregering hvert kvarter
- MINUTE : Minutvis aggregering
- SECOND : Sekundvis aggregering
Vælg granularitet baseret på varigheden af det fænomen, du leder efter, ikke længden af den analyserede periode. En månedlig rapport læses bedst i DAY; en top på ti minutter forsvinder helt på den skala og viser sig kun i QUARTER_HOUR. At gå for lavt ned har også en pris – volumenet af returnerede datapunkter vokser hurtigt, og det gør støjniveauet også.
values
Valget af aggregeringsfunktion ændrer spørgsmålet, du stiller, og her fortjener percentiler din opmærksomhed. AVG på ventetid giver et beroligende gennemsnit, som ingen faktisk oplever; P99 giver ventetiden for dine uheldigste brugere – dem der klager. Til omkostninger bruger du SUM; til ydeevne bruger du en percentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Tilgængelige aggregeringsfunktioner:
- SUM : Total sum
- AVG : Gennemsnit
- MIN : Minimumsværdi
- MAX : Maksimumsværdi
- P50 : Median (50. percentil)
- P90 : 90. percentil
- P99 : 99. percentil
- COUNT : Antal forekomster
- COUNT_DISTINCT : Antal unikke værdier
groupBy
Opdeler resultater efter dimension. I øjeblikket er gruppering efter model tilgængelig, hvilket lader dig se separat forbrug for hver model (grok-4.20-0309-reasoning, grok-4.3 osv.).
Praktiske eksempler
Dagligt forbrug for indeværende måned
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 forespørgsler per time
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-ventetid efter model
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"]
}
}'
Vigtige pointer
- Endpointet
POST /v1/billing/teams/{teamId}/usagesamler alle analyser - 7 tidsmæssige granulariteter tilgængelige, fra SECOND til MONTH
- 9 aggregeringsfunktioner: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parameteren
groupBy: ["model"]opdeler resultater efter model - Brug tidszonen
Europe/Paristil rapporter, der er justeret til dine arbejdstimer