Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Brugsanalyser

Lektion 9 af 14 Opdateret 29. juli 2026 Udvikler
På denne side
  1. Forstå dit API-forbrug
  2. Analyse-endpoint
  3. Forespørgselsparametre
  4. Praktiske eksempler
  5. Vigtige pointer

Forstå dit API-forbrug

Brugsdashboard i xAI-konsollen 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.

7
Tidsenheder
9
Aggregeringer
POST
HTTP-metode
groupBy
Opdeling efter model

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}/usage samler 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/Paris til rapporter, der er justeret til dine arbejdstimer