Usage

Usage is not a stored resource: it is a read-only view computed from AgentRuns for the workspace of the token. Only runs with status=success count, bucketed by the UTC day of finished_at. Cost is in USD, as billed by the AI Gateway.

Two endpoints expose it, both under scope inbox/usage:

Endpoint	Returns
GET /usage/summary	Emails, tokens and cost per day, plus the monthly counters against the workspace limits.
GET /usage/cost	Cost and tokens per LLM model, with a per-day series.

Both accept from and to (YYYY-MM-DD, UTC, inclusive). Without them the range is the last 30 days ending today.

UsageSummary

Field	Type	Description
range.from / range.to	date	Effective range.
totals.emails	int	Emails processed (successful runs).
totals.tokens	int	input_tokens + output_tokens.
totals.input_tokens / totals.output_tokens	int	Split of tokens.
totals.cost	number	USD.
series[]	UsageDay	One entry per day in range: date, emails, tokens, cost. Days without runs are present with zeros.
monthly.emails_used / monthly.emails_limit	int | null	Current calendar month against Workspace.monthly_emails_limit.
monthly.cost_used / monthly.cost_limit	number | null	Current calendar month against Workspace.monthly_cost_limit. Counters reset on the 1st.

UsageCost

Field	Type	Description
models[]	string	Model ids (provider/model) that ran in the range.
by_model[]	object	{ model, cost, tokens }, most expensive first.
series[]	object	{ date, by_model: { "<model id>": cost } }, one per day. Keys of by_model are model ids, not renamed.
totals.cost / totals.tokens	number / int	Whole range.

Example

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