Usage

Usage no es un recurso almacenado: es una vista de solo lectura calculada a partir de los AgentRuns del workspace del token. Solo cuentan las ejecuciones con status=success, agrupadas por el día UTC de finished_at. El costo está en USD, según lo factura el AI Gateway.

Dos endpoints la exponen, ambos bajo el scope inbox/usage:

Endpoint	Devuelve
GET /usage/summary	Correos, tokens y costo por día, más los contadores mensuales frente a los límites del workspace.
GET /usage/cost	Costo y tokens por modelo LLM, con serie diaria.

Ambos aceptan from y to (YYYY-MM-DD, UTC, inclusive). Sin ellos, el rango son los últimos 30 días hasta hoy.

UsageSummary

Campo	Tipo	Descripción
range.from / range.to	date	Rango efectivo.
totals.emails	int	Correos procesados (ejecuciones exitosas).
totals.tokens	int	input_tokens + output_tokens.
totals.input_tokens / totals.output_tokens	int	Desglose de tokens.
totals.cost	number	USD.
series[]	UsageDay	Una entrada por día del rango: date, emails, tokens, cost. Los días sin ejecuciones aparecen en cero.
monthly.emails_used / monthly.emails_limit	int | null	Mes calendario actual frente a Workspace.monthly_emails_limit.
monthly.cost_used / monthly.cost_limit	number | null	Mes calendario actual frente a Workspace.monthly_cost_limit. Los contadores se reinician el día 1.

UsageCost

Campo	Tipo	Descripción
models[]	string	Ids de modelo (provider/model) que se ejecutaron en el rango.
by_model[]	object	{ model, cost, tokens }, del más caro al más barato.
series[]	object	{ date, by_model: { "<model id>": cost } }, una por día. Las claves de by_model son ids de modelo, sin renombrar.
totals.cost / totals.tokens	number / int	Rango completo.

Ejemplo

{
  "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 }
  }
}