Analitici de utilizare
Pe această pagină
Înțelegeți-vă consumul de API
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.
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}/usagecentralizează 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/Parispentru rapoarte aliniate cu programul dumneavoastră de lucru