> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/track-and-control-costs/set-budgets-and-alerts.md). # Set Budgets & Alerts Visibility into your AI spend is only half the picture. The other half is knowing the moment something changes — before a runaway agent, an unexpected usage spike, or a newly onboarded customer turns into a bill you didn't see coming. Revenium's Guardrails let you define exactly what to watch, set the conditions that matter to your business, and get notified through the channels your team already uses — or stop the spend outright. Open **Guardrails** under **Spend Management** in your sidebar to get started. *** ### Guardrails Guardrails brings spend notifications, limits, enforcement, and rule history into one place. Use a Guardrail to define what spend to watch, narrow where the rule applies, and choose whether Revenium should notify your team, enforce a hard cap, or do both. #### How Guardrails work 1. Open **Guardrails** under **Spend Management**. 2. Create a Guardrail and choose the spend you want to watch. 3. Apply the available filters to narrow the rule's scope. 4. Choose a response: notifications, enforcement, or both. 5. Add a custom message when the Guardrail can block a request. 6. Review the Guardrail from the list and use its history to inspect activity. #### Create a Guardrail **Watch spend** Guardrails can monitor two kinds of cost data: * **Provider billing data** — spend synchronized from a connected provider account. Use this data for notifications because it arrives after the provider has processed the usage. * **Revenium-metered data** — usage observed through a supported SDK integration. Cumulative limits on this data can be checked before a request is sent. Provider billing data is not available soon enough for request-time enforcement. To enforce a hard cumulative cap, use Revenium-metered data. **Choose when it applies** Use the filters available in the Guardrail form to limit which metered activity the rule evaluates. The same scope is carried into enforcement so the hard cap applies only to matching requests. **Notify or enforce a cap** Choose the response that fits the rule: * **Notify** — route the event to an available email, Slack, or webhook destination. The destinations shown depend on whether enforcement is also enabled. * **Enforce** — stop a matching SDK-metered request when its cumulative limit has been reached. * **Notify and enforce** — block the request and route the event through the notification options available for the rule. An enforced request does not rely on provider billing data. The check uses cumulative usage metered through the SDK so it can happen before the provider processes the request. **Add a custom block message** Add customer-authored text to explain why a request was blocked and what the developer should do next. Revenium stores the message with the Guardrail and makes it available with the compiled enforcement rule used by the SDK. Keep the message specific to the policy. For example, identify the limit that was reached and the team or process to contact, without including credentials or sensitive account details. #### Review Guardrails and history The Guardrails list combines notification-only rules and enforced limits in one view. Open a rule's history to inspect its recorded activity and follow the rule from configuration into review. #### Read-only access A user with read-only access can inspect the Guardrails list and history. Create, toggle, reset, edit, and delete actions are unavailable. For broader role guidance, see [Manage Users & Teams](/account-and-resources/manage-users-and-teams.md). #### Create a Guardrail from AI by Employee The active AI by Employee view can prefill a new Guardrail with the current employee analysis scope. Review the form before submitting it: opening the hand-off does not create or save a rule automatically. See [AI Assistants](/track-and-control-costs/analyze-ai-tooling-spend.md#ai-by-employee) for the employee analysis workflow. *** ### Cost Controls A Guardrail can be used as an active Cost Control, not just a passive notification. When runtime enforcement is enabled in a supported Revenium SDK, the SDK checks the rule before the model call is sent. Calls blocked by a Cost Control rule do not reach the provider and do not create a metered transaction. Cost Control rules support **dimensional filters** — scope a rule to a specific organization, product, agent, model, or task type rather than applying it globally. For example, a rule that caps spend per customer applies independently per `organizationName` and triggers only when that customer's usage exceeds the budget. Combining dimensional filters with runtime enforcement gives per-customer, per-product, or per-agent guardrails that fire at the call site. Use this mode for production guardrails where the right answer is to stop spend at the call site. Use a notification-only Guardrail when the workload should continue but the team needs visibility through Slack, email, webhook, or Alert history. *** ### :bell: Creating a Guardrail Guardrails are built in four steps: define what you're watching, set the trigger condition, choose how you want to be notified, and review before saving. Open **Guardrails** under **Spend Management** and start a new rule to begin. #### Step 1: Metric & Scope Choose the metric you want the Guardrail to monitor and narrow the scope to the data that matters. **The available metrics cover the full range of AI economics:** * **Total Cost** and **Cost per Transaction** — for spend-level guardrails across your entire operation or per individual request. * **Tokens per Minute** and **Requests per Minute** — for rate-based monitoring, useful for catching agents that are looping or hammering external APIs. * **Error Rate** and **Error Count** — for quality and reliability guardrails, so degrading model performance doesn't go unnoticed. * **Token Count**, **Input Tokens**, **Output Tokens** — for granular usage tracking at the token level. * **Image, Video, and Audio Count** — for multimodal workloads where generation volume drives cost. * **Cost per Image**, **Cost per Second**, **Duration**, **Credits Consumed** — for workload-specific efficiency monitoring. **Scope it down with filters and grouping.** Filters let you focus the Guardrail on a specific dimension — a particular Organization, Credential, Product, Model, Provider, Agent, Subscriber, or Task Type. Grouping goes further: when selected, the Guardrail evaluates the condition separately for each member of that group, so a single Guardrail on Total Cost grouped by Agent will fire individually for any agent that crosses the threshold — not just when the aggregate does. **Choose the data source: Metered or Billed.** Guardrails can watch two different kinds of cost. Two buttons at the top of the Guardrail form — **Metered** and **Billed** — select which: * **Metered** — the default. The Guardrail evaluates against usage metered through your instrumented traffic — the completions, tokens, and events flowing through your SDKs, middleware, and OpenTelemetry exporters. * **Billed** — the Guardrail evaluates against provider-level spend pulled from a connected provider account. Selecting Billed reveals a provider dropdown populated from your connected credentials; pick the provider account you want to watch. Use this to watch cost coming directly from a provider bill, including spend from workloads that aren't yet fully instrumented. Billed Guardrails are evaluated per organization, so each organization's spend is assessed independently and one organization's data cannot bleed into another's evaluation. #### Step 2: Define the Trigger Condition Specify exactly when the Guardrail should fire. Set an **operator** (greater than, less than, greater than or equal to, less than or equal to) and a **threshold value** — the point at which the condition becomes worth acting on. You can also set a **Persist for (optional)** window, so the Guardrail only fires if the condition holds for a sustained period rather than a momentary blip. This keeps notifications meaningful and reduces noise. #### Step 3: Configure Notifications Choose where the notification is sent. At least one channel is required, and you can add multiple. * **Email** — direct to any address, no setup required. * **Slack** — connect your workspace and route notifications to the channel where your team already works. Connect Slack from the **Guardrails** configuration screen before building your first Guardrail. * **Webhook** — send notification payloads to any endpoint. Useful for routing into incident management tools, triggering automated circuit-breaking in your systems, or feeding into your own internal dashboards. Add a webhook URL directly from the notification step, with optional authentication credentials. > 💡 **Tip:** Webhooks are particularly powerful for agentic workflows — the moment an agent's cost behavior breaks its expected pattern, a webhook can trigger an automated response before the problem compounds. #### Step 4: Review & Save A summary of your full Guardrail configuration is shown before saving — metric, scope, filters applied, condition, and notification channels. Review and confirm, and the Guardrail goes live immediately. *** ### :wand-magic-sparkles: One-Click Templates The Guardrails landing screen offers ready-made templates so you can turn on the most common Guardrails without stepping through the full builder. The set shown is tailored to your [role](/get-started/personalize-your-workspace.md) — finance-oriented users see spend-focused templates, engineering-oriented users see reliability and usage templates. Available templates include: * **Spend jumps >20% week-over-week** — catch sudden cost increases before they compound. * **Daily spend over a threshold** — get pinged the day spend crosses a limit you set (the dollar amount is editable before you create it). * **Monthly spend over budget** — know the moment monthly AI spend crosses your budget (editable amount). * **Unusual model cost spike** — flag any single model whose cost spikes versus its baseline. * **Error rate climbing** — catch agents and models failing more than usual. * **Token usage surge** — spot a sudden jump in token consumption. Click a template to create the Guardrail instantly — it applies across all providers and notifies you by **email** by default. Want to add a Slack channel, or fine-tune scope and thresholds first? Choose **Customize** on any template to open it in the full Guardrail builder described above. *** ### :eye: Viewing Alert history The **Alert history** tab on the Spend History page shows every notification that has fired, when it fired, and against what condition. This gives you an audit trail for cost events and makes it straightforward to understand patterns — whether a particular agent consistently trips a spend Guardrail at the same time each day, or a specific customer's usage reliably spikes at month end. *** ### :bell: Guardrails Worth Setting Up **Total Cost > threshold, grouped by Agent** — catches any individual agent whose spend breaks out of expected ranges, without needing a separate Guardrail for each one. **Error Rate > 5%, filtered by Model** — surfaces model-level degradation in production before it affects end users or compounds into failed workflows worth investigating. **Requests per Minute > threshold, filtered by Product** — rate-based monitoring for a specific product tier, useful for catching unexpected bursts of usage that might indicate a misconfigured client or an agent looping. **Cost per Transaction > threshold, grouped by Task Type** — flags when a specific type of task is suddenly becoming significantly more expensive per request than its historical average. > **Through MCP, conversationally.** Setting budget alerts is one of the capabilities the MCP Server explicitly supports. Once an AI assistant is connected to Revenium, alert creation becomes a sentence rather than a four-step form. Tell the agent "alert me on Slack if any single transaction goes over $5", "send me a daily email if total spend exceeds $1,000", or "warn me if AI spend rises more than 20% week over week" and the agent configures it. Useful when the alert idea comes up in conversation — the moment you spot something worth watching, you can wire up the alert without breaking flow. *** ### Related pages * [SDK Setup](/integrations/sdk-setup.md) — connect metered usage for request-time enforcement. * [AI Assistants](/track-and-control-costs/analyze-ai-tooling-spend.md) — analyze employee-level spend and prefill a Guardrail from the active view. * [Build Custom Dashboards & Charts](/track-and-control-costs/build-custom-dashboards-and-charts.md) — review spend changes and cost dimensions before deciding what to control. ### Frequently asked questions
Can a Guardrail enforce a cap using provider billing data? No. Provider billing data arrives after usage has been processed. Hard cumulative caps use Revenium-metered SDK data so the request can be checked before it reaches the provider.
Does opening a Guardrail from AI by Employee create the rule? No. The current view prefills the form. You must review and submit it before the Guardrail is created.
What can a read-only user do? A read-only user can view the Guardrails list and history. They cannot create, toggle, reset, edit, or delete a Guardrail.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.revenium.io/track-and-control-costs/set-budgets-and-alerts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.