Nutzungsanalysen
Auf dieser Seite
Ihr API-Verbrauch verstehen
Eine Rechnung zeigt Ihnen, wie viel Sie ausgegeben haben; dieser Endpunkt erklärt Ihnen, warum. Der Unterschied zwischen Beobachten und Handeln besteht darin, dass der Verbrauch nach Modell, Zeitraum und Ihrer gewählten Granularität aufgeschlüsselt wird. So können Sie einen Anstieg auf ein bestimmtes Modell zu einem bestimmten Zeitpunkt zurückführen.
Die Syntax ist reichhaltiger als der Rest der Management-API – drei Parameterblöcke zur Kombination –, lässt sich aber auf drei Fragen reduzieren: Über welchen Zeitraum, mit welcher Granularität und welche Metrik? Diese Lektion behandelt sie in dieser Reihenfolge. Sie ermöglicht die Analyse des Verbrauchs nach Modell, Zeitraum und mit unterschiedlichen Zeitgranularitäten – wesentliche Daten zur Kostenoptimierung und zur Dimensionierung Ihrer Infrastruktur.
Analyse-Endpunkt
Die Nutzungsanalyse erfolgt über eine POST-Anfrage:
POST /v1/billing/teams/{teamId}/usage
Anforderungsstruktur
{
"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"]
}
}
Diese Anfrage fordert die Summe der verbrauchten Tokens pro Tag, aufgeschlüsselt nach Modell, für März 2026 in UTC. Betrachten Sie dies als Vorlage: In der Praxis ändern Sie von einem Bericht zum anderen im Wesentlichen nur drei Dinge – den Zeitraum, die Zeitgranularität und die Metrik – während der Rest der Struktur identisch bleibt.
Anforderungsparameter
timeRange
Definiert den Analysezeitraum:
- startTime : Start des Zeitraums (Format
YYYY-MM-DD HH:MM:SS) - endTime : Ende des Zeitraums (gleiches Format)
- timezone : Zeitzone für die Datumsinterpretation (z. B.
UTC,Europe/Paris)
timeUnit
Die Zeitgranularität der Ergebnisse. Verfügbare Optionen sind:
- MONTH : monatliche Aggregation
- CALENDAR_WEEK : Aggregation nach Kalenderwoche
- DAY : tägliche Aggregation
- HOUR : stündliche Aggregation
- QUARTER_HOUR : Aggregation in Viertelstunden
- MINUTE : minutengenaue Aggregation
- SECOND : sekundengenaue Aggregation
Wählen Sie die Granularität basierend auf der Dauer des zu untersuchenden Phänomens, nicht auf der Länge des analysierten Zeitraums. Ein monatlicher Bericht ist in DAY gut lesbar; ein zehnminütiger Anstieg verschwindet bei dieser Skala vollständig und zeigt sich erst in QUARTER_HOUR. Eine zu niedrige Granularität hat jedoch einen Preis: Das Volumen der zurückgegebenen Punkte wächst schnell, ebenso wie das Rauschen.
values
Die Wahl der Aggregationsfunktion ändert die gestellte Frage, und hier verdienen Prozentile Ihre Aufmerksamkeit. AVG bei Latenz gibt eine beruhigende Durchschnittswert, den niemand tatsächlich erlebt; P99 gibt die Wartezeit an, die Ihre unglücklichsten Nutzer – die sich beschweren – erdulden. Für Kosten verwenden Sie SUM; für Leistung verwenden Sie ein Perzentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Verfügbare Aggregationsfunktionen:
- SUM : Gesamtsumme
- AVG : Durchschnitt
- MIN : Mindestwert
- MAX : Höchstwert
- P50 : Median (50. Perzentil)
- P90 : 90. Perzentil
- P99 : 99. Perzentil
- COUNT : Anzahl der Vorkommnisse
- COUNT_DISTINCT : Anzahl der eindeutigen Werte
groupBy
Zerlegt die Ergebnisse nach Dimension. Derzeit ist die Gruppierung nach model verfügbar, sodass Sie den separaten Verbrauch jedes Modells sehen können (grok-4.20-0309-reasoning, grok-4.3 usw.).
Praktische Beispiele
Täglicher Verbrauch für den aktuellen Monat
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"]
}
}'
Anzahl der Anfragen pro Stunde
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-Latenz nach 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"]
}
}'
Kernaussagen
- Der Endpunkt
POST /v1/billing/teams/{teamId}/usagebündelt alle Analysen - 7 Zeitgranularitäten verfügbar, von SECOND bis MONTH
- 9 Aggregationsfunktionen: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Der Parameter
groupBy: ["model"]zerlegt die Ergebnisse nach Modell - Verwenden Sie die Zeitzone
Europe/Parisfür Berichte, die mit Ihren Arbeitszeiten übereinstimmen