Аналитика на използването
На тази страница
Разберете потреблението на Вашето API
Фактурата Ви показва колко сте похарчили; този крайна точка (endpoint) Ви обяснява защо. Това е разликата между пасивното наблюдение и активното действие: потреблението се разбива по модел, по период и с избраната от Вас гранулярност, което Ви позволява да свържете всеки скок в трафика с конкретен модел в конкретен момент.
Синтаксисът му е по-богат от останалата част на Management API – три блока параметри за комбиниране, – но в крайна сметка се свежда до три въпроса: за какъв период, с каква гранулярност и каква мярка. Този урок ги разглежда точно в този ред. Той Ви позволява да анализирате потреблението по модел, по период и с различни времеви мащаби – съществени данни за оптимизиране на разходите и оразмеряване на Вашата инфраструктура.
Крайна точка за анализ
Анализът на използването се извършва чрез 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за отчети, синхронизирани с Вашето работно време