Przejdź do głównej treści
Polski— Wybierz język
Menu

Analityka użycia

Lekcja 9 z 14 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Zrozum swoje zużycie API
  2. Punkt końcowy analizy
  3. Parametry żądania
  4. Przykłady praktyczne
  5. Kluczowe wnioski

Zrozum swoje zużycie API

Panel użycia w konsoli xAI 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.

7
Jednostki czasu
9
Agregacje
POST
Metoda HTTP
groupBy
Podział według modelu

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}/usage centralizuje 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/Paris dla raportów dopasowanych do Twoich godzin pracy