# Cost and usage limits

> Field reference for rate limiting, cost tracking, per-stage usage limits, and breach/anomaly usage alerts.

See [Cost and usage governance →](/products/affinidi-trust-fabric/agent-stream/concepts/cost-and-usage-governance.md) for the conceptual model. This page is the field reference for the four related blocks on a surface.

## Rate limiting

Rate limiting throttles requests before they reach the provider, stopping a burst of traffic (a caller retry loop, a runaway script, an unexpected spike) from reaching it at all, and protecting both your own request budget and the provider’s own rate limits. There is no separate enabled toggle: dragging the Rate Limit element onto the canvas is what turns it on, and removing the element turns it off.

| Field | What it does | Default |
| Requests Per Minute | Request-rate ceiling. | 60 |
| Tokens Per Minute | Token-rate ceiling (LLM surfaces). | 100,000 |

## Cost tracking

The LLM, Judge, and Jury stages always count both spend and tokens; this is not something a dashboard toggle governs, and there is currently no dashboard control for overriding per-token prices either. Any provider already in the model catalogue resolves its own pricing automatically. See [Providers: token pricing resolution →](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/providers.md#token-pricing-resolution) for how catalogue pricing resolves.

## Usage limits

Usage limits are the current, per-stage spend/token guardrail mechanism: a hard ceiling that blocks (HTTP 429) further calls for its scope once a monthly cap is reached, enforced pre-call, unlike usage alerts (below), which only notify. Reach for this when a runaway surface, stage, or juror must not be allowed to keep spending past a ceiling you’ve set.

You don’t pick a scope or stage directly: the dashboard sets both automatically from where you configure the limit. Set it on the surface-wide panel and it covers the whole surface (cumulative, the default); set it on a specific LLM, Judge, or juror panel and it covers only that stage. There is no usage-limit control on the Decider panel or on the Jury panel as a whole: only an individual juror’s own panel exposes one, capping that juror alone, not the jury stage together.

- Set the limit on the surface-wide panel for a blanket ceiling across everything the surface does; set it on a specific LLM, Judge, or juror panel when only that one stage needs its own cap.

- To pick a number for Monthly Budget, look at the surface’s own Monitoring-tab cost chart (or, for a caller-facing surface, historical x-agent-stream-cost-usd totals from [response headers](/products/affinidi-trust-fabric/agent-stream/reference/observability/response-headers.md)) for a recent typical month, then add headroom above that for expected growth. This is a hard, request-blocking ceiling, so leave enough margin that a normal usage spike doesn’t trip it.

- Source Monthly Token Cap the same way, from recent monthly token totals on the Monitoring tab.

| Field | What it does | Default |
| Enforce a usage limit | Master switch for this limit, as a toggle. Dashboard label reads “Enforce a usage limit” on the per-stage (LLM/Judge/juror) panels, or “Enforce surface-wide usage limit” on the cumulative/surface-level panel. | Off |
| Monthly Budget (USD) | Monthly USD spend ceiling for the scope. | Not set |
| Monthly Token Cap | Monthly token ceiling for the scope. | Not set |

Validation: at least one of the monthly budget / monthly token cap must be set; a set monthly budget must be non-negative.

## Usage alerts

Usage alerts fire a notification (they do not block the request) through the integrations subsystem when a threshold or anomaly condition is crossed. It’s a deliberately separate mechanism from usage limits, so you get notified with time to react instead of finding out only when requests start failing. A separate enabled switch (default on) gates whether the alerts are evaluated at all; when off, the alerts are retained but never fire, so they can be re-enabled without reconfiguration.

- cost_threshold and token_threshold each evaluate one single request, not cumulative spend: they fire the moment any one execution’s own cost or token count exceeds the threshold. They are not an early-warning proxy for a monthly usage limit; a threshold set as a fraction of a monthly budget will rarely, if ever, fire, since a single request’s cost is normally far below a monthly ceiling. Use them to catch one unexpectedly expensive call, for example an oversized prompt or an unbounded completion.

- error_rate and cost_spike catch a problem a flat ceiling wouldn’t: a sudden jump in failures, or in per-request cost relative to the surface’s own recent baseline, rather than cumulative spend.

Each alert:

| Field | What it does |
| Alert Type | Shown as an unlabeled dropdown whose options read “Cost per request”, “Tokens per request”, “Error rate”, “Cost spike”. |
| Threshold | Per-type meaning below; the dashboard’s field label is dynamic per type: “Cost ceiling (USD)”, “Token ceiling”, “Error-rate ceiling (0–1)”, or “Spike multiplier (× mean)”. |
| Notification Channels | Pick as many integrations as you need. Dashboard label reads “Notify via”. |

Alert types and the corresponding threshold meaning:

| Value | Threshold meaning | Validation |
| cost_threshold | A single request’s own cost, in USD | Must be positive. |
| token_threshold | A single request’s own total token count | Must be positive. |
| error_rate | A fraction in (0, 1] | Must be positive and ≤ 1.0. |
| cost_spike | A multiplier over the rolling baseline mean cost for the surface | Must be strictly greater than 1.0. |

## Related

- [Providers: token pricing resolution](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/providers.md#token-pricing-resolution): How catalogue and override pricing combine to price a call.

- [Teams and attribution](/products/affinidi-trust-fabric/agent-stream/concepts/teams-and-attribution.md): The team attribution block on a surface, and how spend rolls up per member and team.

- [Cost and usage governance concept](/products/affinidi-trust-fabric/agent-stream/concepts/cost-and-usage-governance.md): Why usage limits and breach alerts are two different mechanisms, and how appliance tier limits differ from both.