# Cost and usage governance

> How Agent Stream meters cost and tokens per stage, enforces monthly budgets before they are exceeded, and alerts on anomalies.

Model usage is easy to run up and hard to attribute. Cost and usage governance turns spend from an end-of-month surprise into a value you can cap, attribute, and get alerted on as it happens. [Cost and attribution →](/products/affinidi-trust-fabric/agent-stream/concepts/teams-and-attribution.md)

## Metering runs per stage, not just per call

Cost, tokens, and latency are always counted per stage: the LLM call itself, and separately the Judge, Jury, and Decider stages when they are configured. This is what lets you see that a Jury review is adding a meaningful share of a surface’s spend, rather than seeing only one combined figure for the whole request.

## How a usage limit or monthly ceiling blocks overspend

A surface can enforce a monthly USD budget and a monthly token cap, at the surface level, per stage, or even per individual juror. A request that would exceed a configured cap is blocked with a 429 response rather than being allowed through and billed afterwards. For reasoning models, a separate max_reasoning_tokens governor caps reasoning-token spend per surface, clamping the requested budget before the request reaches the provider; the resulting, post-clamp reasoning effort and budget are exposed to Rego so a policy can gate on what was actually requested.

Usage limits and breach alerts are two different mechanisms, one blocks, the other notifies:

  Usage limitsA hard ceiling. A request that would exceed it is blocked with a 429 before it reaches the provider.
  Breach alertsA notification, not a block. The request still completes; an alert fires afterwards so a person can act on it.

## What triggers a breach or anomaly alert

Beyond hard limits, Agent Stream can fire a notification on:

- a cost threshold or a token threshold being crossed.

- a rolling error rate rising above a configured level.

- a cost spike, an individual execution far above the recent mean cost for that surface.

Alerts route through your existing integrations, such as email, Slack, or a webhook, so a budget breach or a sudden cost anomaly reaches the people who need to act on it, not just a dashboard nobody is watching.

## Provider-side cache tokens

Several providers cache prompt tokens themselves and bill the cached portion at a reduced rate. Agent Stream surfaces this figure explicitly, for example OpenAI’s cached_tokens, Anthropic’s cache_read_input_tokens, and DeepSeek’s prompt_cache_hit_tokens, as distinct from Agent Stream’s own response cache described in [Resilience and caching →](/products/affinidi-trust-fabric/agent-stream/concepts/resilience-and-caching.md). This avoids double-counting a provider’s own cost saving as if it were Agent Stream’s.

## What appliance tier limits control

Everything above governs spend and token usage. Appliance tier limits are a separate mechanism: they cap how many of a given entity you can create, independent of what it costs to run.

Your appliance is provisioned with a maximum count for entities such as users, surfaces, credentials, connections, and gateways, sized to your commercial tier. Attempting to create a new item that would breach one of these limits is blocked outright, with an explanation that names the limit and advises upgrading your appliance tier for more headroom, rather than being allowed through or billed differently.

A Limits tab in Settings lists every enforced limit alongside your appliance’s current usage against it, so you can see how close you are to a ceiling before you hit it.

## Why this matters

- Hard caps stop a runaway integration before it produces a large bill.

- Per-stage attribution shows which part of a governed pipeline, the model call, the Judge, or the Jury, is actually driving cost.

- Team and member rollups. Combined with [Teams and attribution →](/products/affinidi-trust-fabric/agent-stream/concepts/teams-and-attribution.md), the same figures roll up by team, member, and surface.

## Related

- [Teams and attribution](/products/affinidi-trust-fabric/agent-stream/concepts/teams-and-attribution.md): How spend and token usage roll up to members and teams.

- [Pipeline and stages](/products/affinidi-trust-fabric/agent-stream/concepts/pipeline-and-stages.md): The named stages, LLM call, Judge, Jury, Decider, that per-stage metering breaks cost down by.

- [Resilience and caching](/products/affinidi-trust-fabric/agent-stream/concepts/resilience-and-caching.md): How the response cache avoids provider cost on repeated prompts.

- [Observability](/products/affinidi-trust-fabric/agent-stream/concepts/observability.md): Where usage telemetry and per-request cost headers are exposed.