Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Analiżi tal-Użu

Lezzjoni 9 / 14 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Fhem il-Konsum tal-API Tiegħek
  2. Endpoint tal-Analiżi
  3. Parametri tat-Talba
  4. Eżempji Prattiċi
  5. Punti Ewlenin

Fhem il-Konsum tal-API Tiegħek

Dashboard tal-użu fil-konsoll ta' xAI Fattura tgħidlek kemm nefqt; dan l-endpoint jgħidlek għaliex. Dik hija d-differenza bejn l-osservazzjoni u l-azzjoni: il-konsum jinqasam skont il-mudell, skont il-perjodu, u bil-granularità li tagħżel int, u jħallik torbot żieda f’daqqa ma’ mudell speċifiku f’ħin speċifiku.

Is-sintassi tiegħu hija aktar rikka mill-bqija tal-API tal-Ġestjoni—tliet blokok ta’ parametri biex tgħaqqad—imma tinżel għal tliet mistoqsijiet: fuq liema perjodu, b’liema granularità, u liema kejl. Din il-lezzjoni tkoprihom f’dak l-ordni. Tippermettilek tanalizza l-konsum skont il-mudell, skont il-perjodu, u b’granularitajiet temporali differenti—data essenzjali biex tottimizza l-ispejjeż u tiddimensjona l-infrastruttura tiegħek.

7
Unitajiet ta' Ħin
9
Aggregazzjonijiet
POST
Metodu HTTP
groupBy
Tqassim skont il-Mudell

Endpoint tal-Analiżi

L-analiżi tal-użu issir permezz ta’ talba POST:

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

Struttura tat-Talba

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

Din it-talba titlob is-somma tat-tokens ikkunsmati kuljum, maqsuma skont il-mudell, għal Marzu 2026 fi UTC. Ikkunsidraha bħala mudell: fil-prattika, minn rapport għall-ieħor tibdel biss tliet affarijiet—il-perjodu, l-unità ta’ ħin, u l-metrika—filwaqt li l-bqija tal-istruttura tibqa’ identika.

Parametri tat-Talba

timeRange

Jiddefinixxi l-perjodu tal-analiżi:

  • startTime : bidu tal-perjodu (format YYYY-MM-DD HH:MM:SS)
  • endTime : tmiem tal-perjodu (l-istess format)
  • timezone : iż-żona tal-ħin għall-interpretazzjoni tad-data (eż. UTC, Europe/Paris)

timeUnit

Il-granularità temporali tar-riżultati. L-għażliet disponibbli huma:

  • MONTH : aggregazzjoni ta’ kull xahar
  • CALENDAR_WEEK : aggregazzjoni ta’ kull ġimgħa kalendarja
  • DAY : aggregazzjoni ta’ kuljum
  • HOUR : aggregazzjoni ta’ kull siegħa
  • QUARTER_HOUR : aggregazzjoni ta’ kull kwart ta’ siegħa
  • MINUTE : aggregazzjoni ta’ kull minuta
  • SECOND : aggregazzjoni ta’ kull sekonda

Agħżel il-granularità abbażi tad-durata tal-fenomenu li qed tfittex, mhux it-tul tal-perjodu analizzat. Rapport ta’ kull xahar jinqara tajjeb b’DAY; żieda f’daqqa ta’ għaxar minuti tisparixxi kompletament f’dik l-iskala u tidher biss b’QUARTER_HOUR. Li tmur baxx wisq għandu spiża wkoll—il-volum ta’ punti rritornati jikber malajr, u hekk ukoll in-niżla.

values

L-għażla tal-funzjoni ta’ aggregazzjoni tbiddel il-mistoqsija magħmula, u hawnhekk il-perċentili jisħqu l-attenzjoni tiegħek. AVG fuq il-latency jagħti medja li tikkalma li ħadd fil-fatt ma jesperjenza; P99 jagħti l-ħin ta’ stennija li ġarrbu l-utenti l-aktar sfortunati tiegħek—dawk li jilmentaw. Għall-ispiża, uża SUM; għall-prestazzjoni, uża perċentil.

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

Funzjonijiet ta’ aggregazzjoni disponibbli:

  • SUM : somma totali
  • AVG : medja
  • MIN : valur minimu
  • MAX : valur massimu
  • P50 : medjana (il-50 perċentil)
  • P90 : id-90 perċentil
  • P99 : id-99 perċentil
  • COUNT : numru ta’ okkorrenzi
  • COUNT_DISTINCT : numru ta’ valuri distinti

groupBy

Jaqsam ir-riżultati skont id-dimensjoni. Attwalment, il-ħolqien ta’ gruppi skont model huwa disponibbli, u jħallik tara l-konsum separat għal kull mudell (grok-4.20-0309-reasoning, grok-4.3, eċċ.).

Eżempji Prattiċi

Konsum ta’ Kuljum għax-Xahar Attwali

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

Numru ta’ Talbiet kull Siegħa

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

Latenza P99 skont il-Mudell

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

Punti Ewlenin

  • L-endpoint POST /v1/billing/teams/{teamId}/usage jiċċentralizza l-analiżi kollha
  • 7 granularitajiet ta’ ħin disponibbli, minn SECOND sa MONTH
  • 9 funzjonijiet ta’ aggregazzjoni: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
  • Il-parametru groupBy: ["model"] jaqsam ir-riżultati skont il-mudell
  • Uża ż-żona tal-ħin Europe/Paris għal rapporti allinjati mas-sigħat tax-xogħol tiegħek