Spend - Naïve

GET /v1/spend?period=day|week|month|year

Real rows from the tenant spend ledger, grouped by tenant, with each tenant’s declared cap beside its spend. period defaults to month. Anything outside the four values is 400 invalid_input.

{
  "period": { "name": "month", "start": "2026-07-01T00:00:00.000Z" },
  "environment_scoped": false,
  "environment_scoped_note": "this sum spans sandbox and production; the closed reserve path scopes to one environment, so this number can exceed what any single cap counted",
  "buckets": [
    {
      "key": "8f1c…",
      "label": "acme-support",
      "cents": 1840,
      "cap_cents": 5000,
      "class": "reserve",
      "enforced": true,
      "cap_period": "month"
    },
    {
      "key": "b207…",
      "label": "pilot-2",
      "cents": 920,
      "cap_cents": 2000,
      "class": "meter",
      "enforced": false,
      "cap_period": "month"
    }
  ]
}

`class` and `enforced` are the fields that matter

Reading cap_cents without them is how an alert gets mistaken for a ceiling.

`class`	`enforced`	Behaviour at the cap
`reserve`	`true`	The amount is reserved atomically, under an advisory lock, before the action executes. Over-cap actions are refused.
`meter`	`false`	Spend is recorded. A soft cap escalates to approval; no cap meters only. Nothing is refused on the basis of this number.

class is reserve only when the tenant’s budget declares hard: true.

🔴 `environment_scoped: false`

This sum spans sandbox and production. The cap it is compared against does not.The path that reserves spend before an action scopes its sum to one environment. This read path does not. So a tenant’s sandbox spend counts toward the number you see here, but not toward the cap that would refuse it.Practical consequence: cents on this endpoint can exceed cap_cents while no action has ever been refused, and that is not a bug in the cap. If you are building an alert on “spend approaching cap”, either restrict your tenants to one environment or expect false positives from sandbox traffic.

This sum is attribution, not the ledger

A row appears here only when the spend was attributed to a profile. chargeCredits records per-profile platform-credit spend inside the agent-profile context, which is bound around every HTTP request and around every MCP tool call — so both transports are represented. Anything charged outside a resolved subject is not: the legacy orchestration container resolves to the company rather than to its own kit (see the governance gateway), and its usage lands in the company credit ledger with no profile to attribute it to.If you need a total that does not depend on attribution, read GET /v1/billing/transactions — the company credit ledger — and treat this endpoint as the per-tenant governance view rather than as billing.Builds before the current release also omitted all MCP credit spend, because the budget scope was not bound on that transport. If your numbers for an older period look implausibly low for an MCP-heavy tenant, that is why.

Buckets are tenants, not actions

One row per tenant. key is the tenant_user_id; label is the tenant’s label, falling back to its external id, falling back to null. For a per-action breakdown of one tenant, use GET /v1/teams/{team}/tenants/{tenantUserId}/cost — and note that enforced on that endpoint answers a different question and is always false.

Windows

period.start is computed from the requested period, not from any tenant’s own budget window. cap_period on each bucket is that tenant’s actual cap window. If they differ, the spend figure and the cap are measured over different spans — compare cap_period to period.name before dividing one by the other.

{ "period": { "name": "month", "start": "2026-07-01T00:00:00.000Z" }, "environment_scoped": false, "environment_scoped_note": "this sum spans sandbox and production; the closed reserve path scopes to one environment, so this number can exceed what any single cap counted", "buckets": [ { "key": "8f1c…", "label": "acme-support", "cents": 1840, "cap_cents": 5000, "class": "reserve", "enforced": true, "cap_period": "month" }, { "key": "b207…", "label": "pilot-2", "cents": 920, "cap_cents": 2000, "class": "meter", "enforced": false, "cap_period": "month" } ] }

​class and enforced are the fields that matter

​🔴 environment_scoped: false

​This sum is attribution, not the ledger

​Buckets are tenants, not actions

​Windows

`class` and `enforced` are the fields that matter

🔴 `environment_scoped: false`

This sum is attribution, not the ledger

Buckets are tenants, not actions

Windows