Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Análise de Utilização

Aula 9 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Compreenda o Seu Consumo de API
  2. Endpoint de Análise
  3. Parâmetros do Pedido
  4. Exemplos Práticos
  5. Pontos-chave

Compreenda o Seu Consumo de API

Painel de utilização na consola xAI 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.

7
Unidades de Tempo
9
Agregações
POST
Método HTTP
groupBy
Desagregação por Modelo

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}/usage centraliza 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/Paris para relatórios alinhados com o seu horário de trabalho