Analityka użycia
Na tej stronie
Zrozum swoje zużycie API
Faktura mówi Ci, ile wydałeś; ten punkt końcowy wyjaśnia dlaczego. To różnica między bierną obserwacją a działaniem: zużycie jest rozbijane na modele, okresy i wybraną przez Ciebie granulację, co pozwala powiązać skok zużycia z konkretnym modelem w określonym czasie.
Jego składnia jest bogatsza niż w pozostałej części Management API – łączy trzy bloki parametrów – ale sprowadza się do trzech pytań: jaki okres, jaka granulacja czasowa i jaka miara. Ta lekcja omawia je właśnie w tej kolejności. Pozwala analizować zużycie według modelu, okresu i różnych jednostek czasu – są to dane niezbędne do optymalizacji kosztów i doboru wielkości infrastruktury.
Punkt końcowy analizy
Analiza użycia odbywa się poprzez żądanie POST:
POST /v1/billing/teams/{teamId}/usage
Struktura żądania
{
"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"]
}
}
To żądanie prosi o sumę zużytych tokenów na dzień, z podziałem na modele, dla marca 2026 r. w strefie UTC. Traktuj to jako szablon: w praktyce przy każdym raporcie zmieniasz tylko trzy elementy – okres, jednostkę czasu i metrykę – podczas gdy reszta struktury pozostaje identyczna.
Parametry żądania
timeRange
Definiuje okres analizy:
- startTime : początek okresu (format
YYYY-MM-DD HH:MM:SS) - endTime : koniec okresu (ten sam format)
- timezone : strefa czasowa do interpretacji dat (np.
UTC,Europe/Paris)
timeUnit
Granulacja czasowa wyników. Dostępne opcje to:
- MONTH : agregacja miesięczna
- CALENDAR_WEEK : agregacja tygodniowa (tydzień kalendarzowy)
- DAY : agregacja dzienna
- HOUR : agregacja godzinowa
- QUARTER_HOUR : agregacja co 15 minut
- MINUTE : agregacja minutowa
- SECOND : agregacja sekundowa
Wybierz granulację w oparciu o czas trwania zjawiska, którego szukasz, a nie długość analizowanego okresu. Raport miesięczny czytelny jest w skali DAY; dziesięciominutowy skok całkowicie zniknie w takiej skali i ujawni się dopiero przy QUARTER_HOUR. Zbyt duża szczegółowość też ma swoją cenę – liczba zwracanych punktów danych rośnie szybko, podobnie jak szum informacyjny.
values
Wybór funkcji agregującej zmienia postawione pytanie i to właśnie tutaj percentyle zasługują na Twoją uwagę. AVG dla opóźnienia daje uspokajającą średnią, której nikt faktycznie nie doświadcza; P99 pokazuje czas oczekiwania doświadczany przez Twoich najbardziej pechowych użytkowników – tych, którzy składają reklamacje. Dla kosztów użyj SUM; dla wydajności użyj percentyla.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Dostępne funkcje agregujące:
- SUM : suma całkowita
- AVG : średnia
- MIN : wartość minimalna
- MAX : wartość maksymalna
- P50 : mediana (50. percentyl)
- P90 : 90. percentyl
- P99 : 99. percentyl
- COUNT : liczba wystąpień
- COUNT_DISTINCT : liczba wartości unikalnych
groupBy
Rozbija wyniki według wymiaru. Obecnie dostępne jest grupowanie według model, co pozwala zobaczyć osobne zużycie dla każdego modelu (grok-4.20-0309-reasoning, grok-4.3 itd.).
Przykłady praktyczne
Dzienne zużycie w bieżącym miesiącu
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"]
}
}'
Liczba żądań na godzinę
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"]
}
}'
Opóźnienie P99 według modelu
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"]
}
}'
Kluczowe wnioski
- Punkt końcowy
POST /v1/billing/teams/{teamId}/usagecentralizuje całą analitykę - Dostępnych jest 7 granulacji czasowych, od SECOND do MONTH
- 9 funkcji agregujących: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- Parametr
groupBy: ["model"]rozbija wyniki według modelu - Używaj strefy czasowej
Europe/Parisdla raportów dopasowanych do Twoich godzin pracy