Usage

Usage não é um recurso armazenado: é uma visão somente leitura calculada a partir dos AgentRuns do workspace do token. Só execuções com status=success contam, agrupadas pelo dia UTC de finished_at. Custo em USD, como faturado pelo AI Gateway.

Dois endpoints expõem essa visão, ambos sob o scope inbox/usage:

Endpoint	Retorna
GET /usage/summary	E-mails, tokens e custo por dia, mais os contadores mensais versus os limites do workspace.
GET /usage/cost	Custo e tokens por modelo LLM, com série diária.

Ambos aceitam from e to (YYYY-MM-DD, UTC, inclusive). Sem eles, o período são os últimos 30 dias terminando hoje.

UsageSummary

Campo	Tipo	Descrição
range.from / range.to	date	Período efetivo.
totals.emails	int	E-mails processados (execuções com sucesso).
totals.tokens	int	input_tokens + output_tokens.
totals.input_tokens / totals.output_tokens	int	Divisão de tokens.
totals.cost	number	USD.
series[]	UsageDay	Uma entrada por dia do período: date, emails, tokens, cost. Dias sem execuções aparecem zerados.
monthly.emails_used / monthly.emails_limit	int | null	Mês calendário atual versus Workspace.monthly_emails_limit.
monthly.cost_used / monthly.cost_limit	number | null	Mês calendário atual versus Workspace.monthly_cost_limit. Os contadores zeram no dia 1.

UsageCost

Campo	Tipo	Descrição
models[]	string	Ids de modelo (provider/model) que executaram no período.
by_model[]	object	{ model, cost, tokens }, do mais caro para o mais barato.
series[]	object	{ date, by_model: { "<model id>": cost } }, uma por dia. As chaves de by_model são ids de modelo, sem renomear.
totals.cost / totals.tokens	number / int	Período inteiro.

Exemplo

{
  "data": {
    "range": { "from": "2026-08-08", "to": "2026-09-06" },
    "totals": { "emails": 412, "tokens": 913204, "input_tokens": 771010, "output_tokens": 142194, "cost": 3.71 },
    "series": [
      { "date": "2026-08-08", "emails": 14, "tokens": 30122, "cost": 0.12 }
    ],
    "monthly": { "emails_used": 96, "emails_limit": 1000, "cost_used": 0.88, "cost_limit": 50 }
  }
}