Relatórios Avançados de Consumo
Nesta página
Construção de relatórios de consumo
Dados de consumo que ninguém consulta são inúteis. Um relatório só tem valor se responder a uma pergunta que realmente se coloca, e essas perguntas resumem-se a três: o consumo está a aumentar? Ocorreu alguma anomalia? Para onde vai o dinheiro?
As três secções seguintes abordam estas questões pela ordem indicada. Cada uma produz um número sobre o qual pode agir, e não apenas mais um gráfico.
Relatório mensal comparativo
O consumo só faz sentido por comparação. 400 $ num mês não é bom nem mau em termos absolutos: o que importa é saber se esse valor sucede a um mês de 200 $ ou a um de 600 $. Contextualize sempre as alterações com o que sabe sobre a atividade — um aumento de 40 % após o lançamento de uma funcionalidade é esperado; o mesmo aumento sem nenhuma novidade justifica a consulta da secção seguinte.
import requests
import json
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def get_monthly_usage(year, month):
"""Retrieves total consumption for a given month."""
next_month = month + 1 if month < 12 else 1
next_year = year if month < 12 else year + 1
response = requests.post(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
headers={
"Authorization": f"Bearer {MGMT_KEY}",
"Content-Type": "application/json"
},
json={
"analyticsRequest": {
"timeRange": {
"startTime": f"{year}-{month:02d}-01 00:00:00",
"endTime": f"{next_year}-{next_month:02d}-01 00:00:00",
"timezone": "Europe/Paris"
},
"timeUnit": "MONTH",
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "requests", "aggregation": "COUNT"}
],
"groupBy": ["model"]
}
}
)
return response.json()
# Compare March and April 2026
march = get_monthly_usage(2026, 3)
april = get_monthly_usage(2026, 4)
print("=== Comparative Report March vs April 2026 ===")
print(json.dumps(march, indent=2))
print(json.dumps(april, indent=2))
Deteção de anomalias
O desvio-padrão define aqui o que é «anómalo» sem necessidade de estabelecer um limiar arbitrário: um dia que se situe a mais de dois desvios-padrão da sua média foge ao padrão habitual, independentemente do seu volume. Este é o método que se adapta automaticamente à medida que a sua atividade cresce, ao passo que um limiar monetário se torna obsoleto no mês seguinte.
import requests
import statistics
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Retrieve daily consumption for the month
response = requests.post(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
headers={
"Authorization": f"Bearer {MGMT_KEY}",
"Content-Type": "application/json"
},
json={
"analyticsRequest": {
"timeRange": {
"startTime": "2026-03-01 00:00:00",
"endTime": "2026-04-01 00:00:00",
"timezone": "Europe/Paris"
},
"timeUnit": "DAY",
"values": [{"name": "tokens", "aggregation": "SUM"}]
}
}
)
data = response.json()
daily_values = [point.get("value", 0) for point in data.get("dataPoints", [])]
if daily_values:
mean = statistics.mean(daily_values)
stdev = statistics.stdev(daily_values) if len(daily_values) > 1 else 0
threshold = mean + 2 * stdev # Threshold at 2 standard deviations
for i, val in enumerate(daily_values):
if val > threshold:
print(f"Day {i+1}: {val} tokens (anomaly, threshold = {threshold:.0f})")
Discriminação por modelo
Este é o relatório com maior retorno, porque aponta para ações concretas. O custo total não lhe diz o que fazer; a discriminação por modelo, sim — revela tarefas simples encaminhadas para o modelo mais dispendioso, que constituem as poupanças mais fáceis de concretizar numa fatura de API.
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-03-01 00:00:00",
"endTime": "2026-04-01 00:00:00",
"timezone": "UTC"
},
"timeUnit": "MONTH",
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "cost", "aggregation": "SUM"}
],
"groupBy": ["model"]
}
}'
Esta análise pode revelar oportunidades de otimização: se uma grande parte dos seus pedidos utilizar o grok-4.20-0309-reasoning para tarefas simples, a mudança para o grok-4.3 poderá reduzir significativamente os custos.
Relatório semanal automatizado
A entrega automática altera a natureza do exercício: um relatório que tem de ir buscar só é consultado depois do incidente; um relatório que chega é lido antecipadamente. A periodicidade semanal é a adequada para o consumo de API — frequente o suficiente para detetar desvios antes da fatura, mas espaçada o bastante para que continue a abri-lo.
import requests
from datetime import datetime, timedelta
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Previous week
end = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
start = end - timedelta(days=7)
response = requests.post(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
headers={
"Authorization": f"Bearer {MGMT_KEY}",
"Content-Type": "application/json"
},
json={
"analyticsRequest": {
"timeRange": {
"startTime": start.strftime("%Y-%m-%d %H:%M:%S"),
"endTime": end.strftime("%Y-%m-%d %H:%M:%S"),
"timezone": "Europe/Paris"
},
"timeUnit": "DAY",
"values": [
{"name": "tokens", "aggregation": "SUM"},
{"name": "requests", "aggregation": "COUNT"}
],
"groupBy": ["model"]
}
}
)
report = response.json()
print(f"=== Weekly Report {start.date()} → {end.date()} ===")
# Format report for email/Slack
# ... send via your preferred notification tool
Granularidade e desempenho
Escolha da granularidade adequada
| Caso de utilização | Granularidade recomendada |
|---|---|
| Relatório mensal | MONTH |
| Acompanhamento diário | DAY |
| Análise de picos | HOUR ou QUARTER_HOUR |
| Depuração em tempo real | MINUTE |
| Análise detalhada de incidentes | SECOND |
Quanto mais fina for a granularidade, maior será o volume de dados devolvido: ao longo de um mês, a granularidade SECOND produz milhões de pontos, com o correspondente impacto no tempo de resposta e no consumo de memória. A regra prática consiste em escolher a granularidade em função da duração do fenómeno que procura detetar — um pico de alguns minutos é invisível com granularidade MONTH e fica diluído no ruído com granularidade SECOND.
Pontos-chave
- Combine
SUM(total),COUNT(contagem) egroupBy: ["model"]para obter relatórios completos - A deteção de anomalias com desvio-padrão identifica dias de sobreconsumo
- A discriminação por modelo revela oportunidades de otimização de custos
- Adapte a granularidade temporal ao caso de utilização: MONTH para relatórios, HOUR para depuração
- Automatize os relatórios semanais para manter o consumo sob vigilância