Премини към основното съдържание
Български— Изберете език
Меню

Аналитика на използването

Урок 9 от 14 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Разберете потреблението на Вашето API
  2. Крайна точка за анализ
  3. Параметри на заявката
  4. Практически примери
  5. Ключови изводи

Разберете потреблението на Вашето API

Табло за използване в конзолата на xAI Фактурата Ви показва колко сте похарчили; този крайна точка (endpoint) Ви обяснява защо. Това е разликата между пасивното наблюдение и активното действие: потреблението се разбива по модел, по период и с избраната от Вас гранулярност, което Ви позволява да свържете всеки скок в трафика с конкретен модел в конкретен момент.

Синтаксисът му е по-богат от останалата част на Management API – три блока параметри за комбиниране, – но в крайна сметка се свежда до три въпроса: за какъв период, с каква гранулярност и каква мярка. Този урок ги разглежда точно в този ред. Той Ви позволява да анализирате потреблението по модел, по период и с различни времеви мащаби – съществени данни за оптимизиране на разходите и оразмеряване на Вашата инфраструктура.

7
Времеви единици
9
Агрегации
POST
HTTP метод
groupBy
Разбивка по модел

Крайна точка за анализ

Анализът на използването се извършва чрез POST заявка:

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

Структура на заявката

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

Тази заявка иска сумата от консумираните токени на ден, разбита по модел, за март 2026 г. в часовата зона UTC. Разглеждайте я като шаблон: на практика ще променяте само три неща от един отчет към друг – периода, времевата единица и метриката, – докато останалата част от структурата остава идентична.

Параметри на заявката

timeRange

Дефинира периода на анализ:

  • startTime : начало на периода (формат YYYY-MM-DD HH:MM:SS)
  • endTime : край на периода (същият формат)
  • timezone : часова зона за тълкуване на датите (напр. UTC, Europe/Paris)

timeUnit

Времевата гранулярност на резултатите. Наличните опции са:

  • MONTH : месечна агрегация
  • CALENDAR_WEEK : агрегация по календарна седмица
  • DAY : дневна агрегация
  • HOUR : почасова агрегация
  • QUARTER_HOUR : агрегация на всеки 15 минути
  • MINUTE : минутна агрегация
  • SECOND : секундна агрегация

Изберете гранулярността въз основа на продължителността на явлението, което търсите, а не според дължината на анализирания период. Месечният отчет се чете добре с DAY; десетминутен скок изчезва напълно при този мащаб и се вижда само с QUARTER_HOUR. Твърде ниската гранулярност също има цена – обемът на върнатите точки нараства бързо, както и шумът в данните.

values

Изборът на агрегираща функция променя въпроса, който задавате, и тук перцентилите заслужават вниманието Ви. AVG за латентност дава успокояваща средна стойност, която никой реално не изпитва; P99 показва времето за чакане, понесено от най-некъсметливите Ви потребители – тези, които се оплакват. За разходи използвайте SUM; за производителност използвайте перцентил.

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

Налични агрегиращи функции:

  • SUM : обща сума
  • AVG : средна стойност
  • MIN : минимална стойност
  • MAX : максимална стойност
  • P50 : медиана (50-ти перцентил)
  • P90 : 90-ти перцентил
  • P99 : 99-ти перцентил
  • COUNT : брой срещания
  • COUNT_DISTINCT : брой уникални стойности

groupBy

Разбива резултатите по измерение. В момента е налично групиране по model, което Ви позволява да видите отделното потребление за всеки модел (grok-4.20-0309-reasoning, grok-4.3 и др.).

Практически примери

Дневна консумация за текущия месец

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

Брой заявки на час

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 латентност по модел

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

Ключови изводи

  • Крайната точка POST /v1/billing/teams/{teamId}/usage централизира цялата аналитика
  • Налични са 7 времеви гранулярности, от SECOND до MONTH
  • 9 агрегиращи функции: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
  • Параметърът groupBy: ["model"] разбива резултатите по модел
  • Използвайте часовата зона Europe/Paris за отчети, синхронизирани с Вашето работно време