# Cost Controls
Cost Controls use Revenium's usage metering data to enforce configured AI spend and usage limits. You define a **Cost Control Rule** in the Revenium app; the [Revenium SDK](/integrations/sdk-setup.md) running inside your application evaluates incoming AI requests against that rule and blocks the request when the limit is reached.
The SDK evaluates rules locally using a cached ruleset that refreshes every 60 seconds by default (configurable via `REVENIUM_CB_POLL_INTERVAL_SECONDS`). If Revenium is unreachable, the SDK continues using its last cached ruleset. If no ruleset has been fetched, enforcement does not run.
{% hint style="success" %}
**New to Revenium?** Cost Controls require Revenium AI metering. If you haven't configured metering yet, start with the [5-Minute Quickstart](/get-started/quickstart/5-minute-quickstart.md).
{% endhint %}
## How it fits with Budgets & Alerts
Cost Controls work alongside [Budgets & Alerts](/track-and-control-costs/set-budgets-and-alerts.md). Alerts notify you when a metric crosses a threshold, budget views show usage against configured budgets, and Cost Controls enforce configured limits before the AI request proceeds.
| Feature | When it fires | What it does |
| ------------------------- | --------------------------------------------------- | ---------------------------------------------------- |
| Cost & Performance Alerts | Metric crosses a threshold | **Notifies** via email / Slack |
| Budget Monitoring | Tracking view of all threshold-based budgets | **Visualizes** pace and risk |
| **Cost Controls** | Rule's hard limit is crossed on an incoming request | **Enforces** — blocks the request before the AI call |
Use these features together when you need both visibility and enforcement. For example, configure an alert at 80% of a monthly limit, use the budget view to review usage trends, and use Cost Controls to enforce the limit for a customer, model, provider, or other scope.
***
## Anatomy of a Cost Control Rule
A cost control rule is defined by five things:
1. **Metric** — what you're counting (total cost, token count, error count, …).
2. **Window** — the rolling period you're counting over (daily / weekly / monthly / quarterly).
3. **Hard limit** — the threshold that trips enforcement.
4. **Action** — what the SDK does when the limit is crossed. New rules use **Block** (the only action selectable in the UI today). `THROTTLE` and `WARN_ONLY` are legacy actions retained for historical rules and event-log rendering only.
5. **Scope** — optional filters (this rule only applies to OpenAI) and group-by (broken out per model).
{% hint style="warning" %}
**Total Cost and unpriced models:** Total Cost enforcement requires the model's pricing to be configured in your pricing tier. If a model lacks pricing data, events for that model contribute $0 to the rule and won't trip the threshold. Use Token Count if you need enforcement regardless of pricing coverage.
{% endhint %}
Cost control rules also support these options:
* **Shadow mode** — the rule evaluates but does NOT enforce. Used to validate a limit before promoting it. All new rules default to shadow.
* **Warning threshold** — a soft threshold below the hard limit that fires a warning notification without blocking.
***
## Creating your first Cost Control Rule
Find Cost Controls in the left nav menu or via the search bar in the Revenium app.
1. **Open Cost Controls** — find Cost Controls in the left nav menu or via the search bar. You'll see the list of existing rules for your team.
2. **Click Create Cost Control Rule** — the dialog walks you through the required pieces.
3. **Name the rule and pick a metric** — give it a descriptive name (this appears in notifications and the enforcement event log) and pick the cumulative metric you want to cap.
4. **Choose a window and limit** — daily / weekly / monthly / quarterly. Windows are calendar-aligned in UTC. Set the hard limit; optionally set a warning threshold below it.
5. **Note the action** — new rules use **Block**. The Cost Controls form does not surface an action selector today; the rule is created with `action: BLOCK`.
6. **Leave Shadow mode on** — it's on by default. Leave it on for the first evaluation period so you can preview what would happen before promoting to enforce.
7. **Scope it (optional)** — add filters or a Group by dimension to narrow the rule (e.g. only OpenAI, broken out per model).
8. **Attach notification channels (optional)** — Slack + webhook channels configured under **Settings → Integrations → Notification Providers** can receive alerts when the rule fires.
9. **Save.** The rule is available for evaluation after the SDK receives the updated ruleset. Because shadow mode is on, requests are not blocked, but matching events appear in the enforcement event log after the rule is evaluated.
***
## Shadow mode vs enforce
New rules start in **shadow mode**. In shadow mode, the rule matches traffic, aggregates usage, sends configured notifications, and records events, but does not block requests.
Shadow mode is the default so you can review matching behavior before enforcement. It lets you:
* See how much traffic a rule would have blocked over a real evaluation window.
* Catch filter mismatches before they affect customers.
* Validate threshold tuning — if a rule would have fired 50 times in the first hour, your threshold is too low.
* Tune notification noise — test the alerting flow without blocking.
### Promoting to enforce
After you confirm the rule matches the intended traffic and threshold, turn **Shadow mode** off. Subsequent hard-limit crossings execute the rule's declared action — **Block** for new rules.
You can do this from the UI by editing the rule and toggling shadow off.
{% hint style="success" %}
**Best practice:** run a new rule in shadow for at least one full window (a monthly rule for a full month, a daily rule for a full day) before promoting. This gives you a more complete view of usage over the rule's evaluation period.
{% endhint %}
***
## Enforcement actions
When a non-shadow Cost Control rule's hard limit is crossed, the SDK executes the rule's action. New rules support only **Block** today:
| Action | What happens |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Block | The SDK raises a cost-limit exception **before** the AI provider call. The provider never sees the request. Customer code catches the exception and surfaces a graceful error to the end user. |
### Legacy actions (historical)
`THROTTLE` and `WARN_ONLY` are retained in the API and event-log rendering for rules created before the action selector was removed from the UI. They are **not selectable** when creating a new rule today. If you see these actions in the enforcement event log, they originate from a legacy rule.
### Fail-open by default
If the SDK can't reach Revenium (network issue, Revenium outage, expired API key), **enforcement fails open**. The SDK logs the failure and continues using its last cached ruleset. If no ruleset has been fetched, enforcement does not run.
{% hint style="warning" %}
**Stop enforcement for a rule.** Disable the rule in the UI. SDKs pick up the change on the next ruleset refresh. Re-enable the rule when you want enforcement to resume.
{% endhint %}
***
## SDK setup and configuration
Cost Controls require the Revenium SDK in your application. Use the SDK documentation for language-specific environment variables, exception fields, code examples, and troubleshooting:
| SDK | Where to find it | What it covers |
| ----------- | ------------------------------------------- | ------------------------------------------ |
| **Python** | See [SDK Setup](/integrations/sdk-setup.md) | Python SDK setup and supported providers. |
| **Node.js** | See [SDK Setup](/integrations/sdk-setup.md) | Node.js SDK setup and supported providers. |
| **Go** | See [SDK Setup](/integrations/sdk-setup.md) | Go SDK setup and supported providers. |
Each SDK README also links back here for the conceptual walkthrough.
{% hint style="info" %}
Check each SDK README and changelog for current Cost Controls support by language and provider.
{% endhint %}
***
## Reading the enforcement event log
Every evaluation that blocks (or would-block, in shadow mode) writes an immutable event to the **Enforcement Events** log. The log lives on the rule's detail page and can be filtered to a single rule or span all rules for your team.
Each event captures when the evaluation happened, which rule fired, the action declared, whether it was shadow or live, the metric / current value / threshold / percentage at the moment of evaluation, and a masked API-key hint so you can trace it back to the originating request.
Filter the log to shadow events only while tuning a new rule. This shows which requests matched the rule without enforcing the action.
***
## Disabling vs deleting a rule
* **Disable** — the rule is retained for history but skipped at evaluation time. Re-enable any time. Use this to pause a rule temporarily.
* **Delete** — soft-delete. Removed from evaluation but the event history persists for audit. You cannot un-delete; create a new rule if you need the semantic back.
***
## FAQ
How quickly does a new rule start enforcing?
The SDK polls the compiled-rules endpoint every 60 seconds by default (configurable via `REVENIUM_CB_POLL_INTERVAL_SECONDS`). Allow up to one full poll interval for a new rule to reach every running instance of your application. First-time rule creation may take slightly longer because the server's rule compiler must produce the compiled payload — typical end-to-end time is under two minutes.
What happens if my application can't reach Revenium?
The SDK fails open. It logs the failure and continues using its last cached ruleset. If it has never successfully fetched a ruleset, enforcement does not run.
Does enforcement add latency to my AI calls?
The SDK's enforcement check is an in-memory comparison against the cached ruleset. Rule-cache refresh happens in a background task and does not block the request path.
Can I have multiple rules on the same metric?
Yes. Rules are evaluated independently — every matching rule runs. If two rules would both block the request, the first to fail wins. Use the warning threshold on a blocking rule to get notified before the hard limit is hit, or apply both a global and a per-group cap. For notification-only flows on the same metric, see [Set Budgets & Alerts](/track-and-control-costs/set-budgets-and-alerts.md).
How do I cap spend across all my customers, not per-customer?
Create a rule with **no filters** and **no group by**. It aggregates all your team's AI spend for the window against a single limit. Pair it with a per-customer rule (filter by organization, or group by organization) if you want both a fleet cap and a per-customer cap.
How do I stop enforcement for a rule?
Disable the rule from the Cost Controls page. SDKs pick up the change on the next ruleset refresh.
Re-enable the rule when you want enforcement to resume.
***
## See also
{% hint style="info" %}
**Notification channels** for Cost Control rules (Slack, webhook) are configured in the Revenium app under **Settings → Integrations → Notification Providers**. Once configured there, they appear in the channel picker on the Cost Control rule form.
{% endhint %}
* [Set Budgets & Alerts](/track-and-control-costs/set-budgets-and-alerts.md) — adjacent feature: alerts and budget tracking for notification-only flows.
* [SDK Setup](/integrations/sdk-setup.md) — install the Revenium SDK that evaluates Cost Control rules.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.revenium.io/track-and-control-costs/cost-controls.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.