Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Gebruiksanalyses

Les 9 van 14 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Inzicht in uw API-verbruik
  2. Analyse-eindpunt
  3. Verzoekparameters
  4. Praktische voorbeelden
  5. Belangrijkste punten

Inzicht in uw API-verbruik

Gebruiksoverzicht in de xAI-console Een factuur vertelt u hoeveel u hebt uitgegeven; dit eindpunt vertelt u waarom. Dat is het verschil tussen observeren en handelen: het verbruik wordt uitgesplitst per model, per periode en met de door u gekozen granulariteit, zodat u een piek kunt koppelen aan een specifiek model op een specifiek tijdstip.

De syntaxis is rijker dan bij de rest van de Management API—drie blokken parameters om te combineren—maar het komt neer op drie vragen: over welke periode, met welke granulariteit en welke maatstaf. Deze les behandelt ze in die volgorde. Het stelt u in staat om het verbruik per model, per periode en met verschillende tijdgranulariteiten te analyseren—essentiële gegevens voor het optimaliseren van kosten en het dimensioneren van uw infrastructuur.

7
Tijdseenheden
9
Aggregaties
POST
HTTP-methode
groupBy
Uitsplitsing per model

Analyse-eindpunt

Gebruiksanalyse verloopt via een POST-verzoek:

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

Structuur van het verzoek

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

Dit verzoek vraagt om de som van de verbruikte tokens per dag, uitgesplitst per model, voor maart 2026 in UTC. Beschouw dit als een sjabloon: in de praktijk wijzigt u van rapport tot rapport slechts drie dingen—de periode, de tijdseenheid en de metriek—terwijl de rest van de structuur identiek blijft.

Verzoekparameters

timeRange

Definieert de analyseperiode:

  • startTime : begin van de periode (formaat YYYY-MM-DD HH:MM:SS)
  • endTime : einde van de periode (zelfde formaat)
  • timezone : tijdzone voor datuminterpretatie (bijv. UTC, Europe/Paris)

timeUnit

De tijdgranulariteit van de resultaten. Beschikbare opties zijn:

  • MONTH : maandelijkse aggregatie
  • CALENDAR_WEEK : aggregatie per kalenderweek
  • DAY : dagelijkse aggregatie
  • HOUR : uurlijkse aggregatie
  • QUARTER_HOUR : aggregatie per kwartier
  • MINUTE : minutelijke aggregatie
  • SECOND : secondelijke aggregatie

Kies de granulariteit op basis van de duur van het fenomeen dat u zoekt, niet op basis van de lengte van de geanalyseerde periode. Een maandrapport leest prettig in DAY; een piek van tien minuten verdwijnt volledig op die schaal en komt alleen naar voren in QUARTER_HOUR. Te laag gaan heeft ook een prijs: het volume van de geretourneerde punten groeit snel, en de ruis eveneens.

values

De keuze van de aggregatiefunctie verandert de gestelde vraag, en hier verdienen percentielen uw aandacht. AVG op latentie geeft een geruststellend gemiddelde dat niemand daadwerkelijk ervaart; P99 geeft de wachttijd die uw minst gelukkige gebruikers ondergaan—degenen die klagen. Gebruik voor kosten SUM; voor prestaties gebruikt u een percentiel.

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

Beschikbare aggregatiefuncties:

  • SUM : totale som
  • AVG : gemiddelde
  • MIN : minimumwaarde
  • MAX : maximumwaarde
  • P50 : mediaan (50e percentiel)
  • P90 : 90e percentiel
  • P99 : 99e percentiel
  • COUNT : aantal voorkomens
  • COUNT_DISTINCT : aantal verschillende waarden

groupBy

Splitst resultaten uit per dimensie. Momenteel is groepering op model beschikbaar, zodat u het verbruik per model afzonderlijk kunt zien (grok-4.20-0309-reasoning, grok-4.3, enz.).

Praktische voorbeelden

Dagelijks verbruik voor de huidige maand

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

Aantal verzoeken per uur

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

Belangrijkste punten

  • Het eindpunt POST /v1/billing/teams/{teamId}/usage centraliseert alle analyses
  • 7 tijdgranulariteiten beschikbaar, van SECOND tot MONTH
  • 9 aggregatiefuncties: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
  • De parameter groupBy: ["model"] splitst resultaten uit per model
  • Gebruik de tijdzone Europe/Paris voor rapporten die zijn afgestemd op uw werktijden