Cost - Naïve

GET /v1/teams/{team}/tenants/{tenantUserId}/cost?by=action

Real rows from the tenant spend ledger, grouped by action type.

This reads naive’s own ledger on both runtimes, and a durable tenant’s model spend is not in it. There is no durable lane here: the query is tenant_spend_events for (company, tenant) either way. A hermes tenant’s compute is metered off its running task and lands there. A durable tenant’s compute is spent inside the runtime, and it reaches this ledger only if both of the following hold:

the runtime’s usage push is delivered and accepted — it is reported to POST /v1/vetta/{company}/{tenant}/usage, which refuses any tenant not actually placed on the durable runtime; and
that tenant has an agent-profile budget group, because the ledger row is written as budget attribution and is skipped when there is none.

Where either fails, buckets comes back [] — a 200 with an empty list, not a refusal and not a spend_unavailable_because. An empty buckets is not the same as “this tenant spent nothing.” Confirm placement and delivery before reading a zero here as a fact about money.The same caveat applies to spend.spent_cents on the team header, which reads the same table.

Query parameters

Name	Values	Notes
`by`	`action`	The only accepted value. Anything else is `400 invalid_input` with the message `by must be "action" (the only bucketing this build can compute)`. Bucketing by role or by model needs a manifest, and none is stored.

{
  "period": { "name": "month", "start": "2026-07-01T00:00:00.000Z" },
  "buckets": [
    { "key": "llm.chat",   "cents": 1240, "class": "meter", "cap_cents": null, "enforced": false },
    { "key": "email.send", "cents":  600, "class": "meter", "cap_cents": null, "enforced": false }
  ]
}

The window is the tenant’s, not the calendar’s

period comes from the tenant’s AccountKit budget. If the cap resets weekly, this number is a week. Reporting spend over a month while the cap resets weekly gives a number that looks like a fraction of a cap and is not one. With no budget declared, the window falls back to the calendar month, because that is the conventional reporting window — and cap_cents is null, because there is nothing to be a fraction of.

🔴 `enforced` on this endpoint is always `false`, and that is not a bug

Two endpoints on this surface report a field called enforced, and they are answering different questions.

Endpoint	`enforced` means
`GET …/{tenantUserId}`	Is this tenant’s declared cap a hard cap? `true` when the AccountKit budget is hard.
`GET …/cost` (this page)	Does anything refuse a call on the basis of this bucket? Always `false`.

The per-bucket rows here are recorded after the spend happens. A post-hoc record is a meter, never a reserve, and class says meter on every row for the same reason. Calling a post-hoc record a reserve is how an alert gets mistaken for a ceiling.If you want to know whether a cap will actually stop anything, read spend.class / spend.enforced on the team header, or GET /v1/spend for every tenant at once.

GET /v1/spend — the company-wide view, one row per tenant, with each tenant’s cap and whether it is enforced
GET /v1/limits — the ceilings that bound this surface

{ "period": { "name": "month", "start": "2026-07-01T00:00:00.000Z" }, "buckets": [ { "key": "llm.chat", "cents": 1240, "class": "meter", "cap_cents": null, "enforced": false }, { "key": "email.send", "cents": 600, "class": "meter", "cap_cents": null, "enforced": false } ] }

​Query parameters

​The window is the tenant’s, not the calendar’s

​🔴 enforced on this endpoint is always false, and that is not a bug

​Related

Query parameters

The window is the tenant’s, not the calendar’s

🔴 `enforced` on this endpoint is always `false`, and that is not a bug

Related