Salt la conținutul principal
Română— Alege o limbă
Meniu

Analitici de utilizare

Lecția 9 din 14 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Înțelegeți-vă consumul de API
  2. Endpoint de analiză
  3. Parametrii cererii
  4. Exemple practice
  5. Puncte cheie

Înțelegeți-vă consumul de API

Tabloul de bord de utilizare în consola xAI O factură vă spune cât ați cheltuit; acest endpoint vă explică de ce. Aceasta este diferența dintre a observa și a acționa: consumul este defalcat pe model, pe perioadă și la granularitatea aleasă de dumneavoastră, permițându-vă să corelați un vârf de trafic cu un model specific la un moment dat.

Sintaxa sa este mai bogată decât restul API-ului de Management—trei blocuri de parametri de combinat—dar se rezumă la trei întrebări: pe ce perioadă, la ce granularitate și ce măsurătoare. Această lecție le abordează în această ordine. Vă permite să analizați consumul pe model, pe perioadă și cu diferite granularități temporale—date esențiale pentru optimizarea costurilor și dimensionarea infrastructurii.

7
Unități de timp
9
Agregări
POST
Metodă HTTP
groupBy
Defalcare pe model

Endpoint de analiză

Analiza utilizării se face printr-o cerere POST:

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

Structura cererii

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

Această cerere solicită suma tokenilor consumați pe zi, defalcată pe model, pentru luna martie 2026 în UTC. Considerați-o un șablon: în practică, veți modifica doar trei elemente de la un raport la altul—perioada, unitatea de timp și metrica—în timp ce restul structurii rămâne identic.

Parametrii cererii

timeRange

Definește perioada de analiză:

  • startTime : începutul perioadei (format YYYY-MM-DD HH:MM:SS)
  • endTime : sfârșitul perioadei (același format)
  • timezone : fusul orar pentru interpretarea datelor (de ex. UTC, Europe/Paris)

timeUnit

Granularitatea temporală a rezultatelor. Opțiunile disponibile sunt:

  • MONTH : agregare lunară
  • CALENDAR_WEEK : agregare pe săptămână calendaristică
  • DAY : agregare zilnică
  • HOUR : agregare orară
  • QUARTER_HOUR : agregare pe sfert de oră
  • MINUTE : agregare pe minut
  • SECOND : agregare pe secundă

Alegeți granularitatea în funcție de durata fenomenului pe care îl căutați, nu de lungimea perioadei analizate. Un raport lunar se citește bine în DAY; un vârf de zece minute dispare complet la acea scară și apare doar în QUARTER_HOUR. Coborârea prea jos are și ea un cost—volumul de puncte returnate crește rapid, la fel ca și zgomotul de fond.

values

Alegerea funcției de agregare schimbă întrebarea pusă, iar aici percentilii merită atenția dumneavoastră. AVG pe latență oferă o medie reconfortantă pe care nimeni nu o experimentează realmente; P99 oferă timpul de așteptare îndurat de cei mai ghinioniști utilizatori ai dumneavoastră—cei care se plâng. Pentru cost, folosiți SUM; pentru performanță, folosiți un percentil.

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

Funcții de agregare disponibile:

  • SUM : suma totală
  • AVG : media
  • MIN : valoarea minimă
  • MAX : valoarea maximă
  • P50 : mediana (percentila 50)
  • P90 : percentila 90
  • P99 : percentila 99
  • COUNT : numărul de apariții
  • COUNT_DISTINCT : numărul de valori distincte

groupBy

Defalcă rezultatele pe dimensiuni. În prezent, gruparea după model este disponibilă, permițându-vă să vedeți consumul separat pentru fiecare model (grok-4.20-0309-reasoning, grok-4.3, etc.).

Exemple practice

Consum zilnic pentru luna curentă

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

Numărul de cereri pe oră

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

Latența P99 pe 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"]
    }
  }'

Puncte cheie

  • Endpoint-ul POST /v1/billing/teams/{teamId}/usage centralizează toate analiticele
  • 7 granularități temporale disponibile, de la SECOND la MONTH
  • 9 funcții de agregare: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
  • Parametrul groupBy: ["model"] defalcă rezultatele pe model
  • Folosiți fusul orar Europe/Paris pentru rapoarte aliniate cu programul dumneavoastră de lucru