Gebruiksanalyses
Op deze pagina
Inzicht in uw API-verbruik
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.
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}/usagecentraliseert 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/Parisvoor rapporten die zijn afgestemd op uw werktijden