Análise de Utilização
Nesta página
Compreenda o Seu Consumo de API
Uma fatura indica-lhe quanto gastou; este endpoint explica-lhe porquê. Essa é a diferença entre observar e agir: o consumo desagrega-se por modelo, por período e com a granularidade que escolher, permitindo-lhe associar um pico de tráfego a um modelo específico num momento exato.
A sua sintaxe é mais rica do que a do restante Management API — três blocos de parâmetros para combinar —, mas resume-se a três questões: durante qual período, com que granularidade e que medida. Esta lição aborda-as nessa ordem. Permite-lhe analisar o consumo por modelo, por período e com diferentes granularidades temporais — dados essenciais para otimizar custos e dimensionar a sua infraestrutura.
Endpoint de Análise
A análise de utilização ocorre através de um pedido POST:
POST /v1/billing/teams/{teamId}/usage
Estrutura do Pedido
{
"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"]
}
}
Este pedido solicita a soma dos tokens consumidos por dia, desagregada por modelo, para março de 2026 em UTC. Encare-o como um modelo: na prática, apenas alterará três elementos de um relatório para outro — o período, a unidade de tempo e a métrica —, mantendo-se idêntica toda a restante estrutura.
Parâmetros do Pedido
timeRange
Define o período de análise:
- startTime : início do período (formato
YYYY-MM-DD HH:MM:SS) - endTime : fim do período (mesmo formato)
- timezone : fuso horário para interpretação das datas (ex.:
UTC,Europe/Paris)
timeUnit
A granularidade temporal dos resultados. As opções disponíveis são:
- MONTH : agregação mensal
- CALENDAR_WEEK : agregação por semana civil
- DAY : agregação diária
- HOUR : agregação horária
- QUARTER_HOUR : agregação por quarto de hora
- MINUTE : agregação por minuto
- SECOND : agregação por segundo
Escolha a granularidade com base na duração do fenómeno que procura detetar, e não na extensão do período analisado. Um relatório mensal lê-se bem em DAY; um pico de dez minutos desaparece completamente nessa escala e só surge em QUARTER_HOUR. Descer demasiado também tem um custo: o volume de pontos devolvidos cresce rapidamente, assim como o ruído.
values
A escolha da função de agregação altera a pergunta colocada, e é aqui que os percentis merecem a sua atenção. AVG na latência fornece uma média tranquilizadora que ninguém experiencia realmente; P99 indica o tempo de espera suportado pelos seus utilizadores mais azarados — aqueles que se queixam. Para custos, utilize SUM; para desempenho, utilize um percentil.
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "tokens", "aggregation": "AVG"},
{"name": "latency", "aggregation": "P99"}
]
Funções de agregação disponíveis:
- SUM : soma total
- AVG : média
- MIN : valor mínimo
- MAX : valor máximo
- P50 : mediana (percentil 50)
- P90 : percentil 90
- P99 : percentil 99
- COUNT : número de ocorrências
- COUNT_DISTINCT : número de valores distintos
groupBy
Desagrega os resultados por dimensão. Atualmente, está disponível o agrupamento por model, permitindo-lhe visualizar o consumo separado para cada modelo (grok-4.20-0309-reasoning, grok-4.3, etc.).
Exemplos Práticos
Consumo Diário do Mês Atual
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"]
}
}'
Número de Pedidos por Hora
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"]
}
}'
Latência P99 por Modelo
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"]
}
}'
Pontos-chave
- O endpoint
POST /v1/billing/teams/{teamId}/usagecentraliza todas as análises - 7 granularidades temporais disponíveis, de SECOND a MONTH
- 9 funções de agregação: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
- O parâmetro
groupBy: ["model"]desagrega os resultados por modelo - Utilize o fuso horário
Europe/Parispara relatórios alinhados com o seu horário de trabalho