Budgets

• Cap monthly spend per customer or tenant by scoping a budget to an Identity.
• Prevent a staging or CI environment from consuming production credits by scoping a budget to its API Key.
• Limit exposure to an expensive provider or model during evaluation by scoping a budget to a Provider or Model.
• Enforce a hard workspace-wide cost ceiling as a safety net by scoping a budget to the Workspace.
• Control spend for a time-boxed experiment using a One-time reset period with an expiration date.

​

Overview

​

Monitor usage

• A metric card for each configured limit (Total spend, Tokens, Req per minute) shows current usage, a progress bar, and percentage consumed.
• Scope, Resets period, Renews in countdown, and Expires date appear at the top.

• Click Adjust limits to edit the budget’s period limits or expiration date.
• Click Add threshold in the Alerts section to set up an alert.
• Click Delete Budget to permanently remove it. Enforcement stops immediately.

​

Create a budget

1

Open the creation dialog

Click Create in the top-right corner of the Budgets page.

2

Set the scope

Under Scope, select what the budget Applies to:

Option	Description
Workspace	Applies to the entire workspace.
Project	Applies to a specific project.
Identity	Applies to a contact by external ID.
API Key	Applies to a specific API key.
Provider	Applies to all requests to a provider. Matches the provider segment of the model reference (openai in openai/gpt-4o).
Model	Applies to a specific model, matched by the full model reference as sent in the request (openai/gpt-4o).

For all scope types except Workspace, a second field appears to select the specific target (for example, which API key or which identity).

Only one budget is allowed per target. If a budget already exists for the selected target, an inline error is shown and the budget cannot be created until a different target is selected.

See Budget levels and interaction for how budgets at different levels apply to the same request.

3

Configure period limits

Under Period limits, set the Reset period (required) and one or more of the following limits:

Limit	Unit	Description
Cost	USD	Maximum spend allowed per reset period.
Tokens limit	K Tokens	Token cap per reset period, in thousands.
Requests per minute	Req/min	Rate cap enforced every minute, at all times.

Leave a limit at 0 to leave it unconfigured. At least one limit must be set to a non-zero value to create the budget.Reset periods follow a fixed schedule:

Period	Resets at
Daily	Midnight UTC
Weekly	Monday midnight UTC
Monthly	1st of the month, midnight UTC
Yearly	January 1st, midnight UTC
One-time	Does not reset. Limit applies for the lifetime of the budget.

Requests per minute is a rolling rate cap enforced continuously, independent of the reset period.

If a budget is exhausted before the period resets, an admin can increase its limit to unblock further usage immediately. Existing usage is not removed; the higher limit simply allows the entity to consume more within the current period.

4

Set an expiration date (optional)

Under Expiration, set an Expiration date if the budget should stop enforcing after a specific date. Leave it as Never expires for an indefinite budget.

5

Create the budget

Click Create budget. The budget appears in the list immediately and begins enforcing on the next request.

​

Edit or delete a budget

• Edit: update the period limits or expiration date. The scope and target cannot be changed after creation.
• Delete: permanently removes the budget. Enforcement stops immediately.

​

Configure alerts

​

Create a notifier

​

Create an alert

1

Add a threshold

In the Alerts section, click Add threshold.

2

Set the threshold percentage

Enter a whole number between 1 and 100. Each budget allows only one alert per threshold percentage; duplicate thresholds are rejected.

3

Add notifiers

Click Add notifiers and search for one or more already-created notifiers to receive the alert. At least one notifier is required. Each alert allows a maximum of 10 notifiers.

4

Save the alert

Click Add alert (or Save changes when editing an existing alert).

​

Examples

​

Send notifications to a Microsoft Teams channel

export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    let envelope;
    try {
      envelope = await request.json();
    } catch {
      return new Response("Invalid JSON body", { status: 400 });
    }
    const links = envelope.links ?? [];

    const card = {
      "@type": "MessageCard",
      "@context": "http://schema.org/extensions",
      themeColor: severityColor(envelope.severity),
      title: envelope.title,
      text: envelope.body,
      sections: [
        {
          facts: [
            { name: "Severity", value: envelope.severity },
            ...links.map((link) => ({ name: link.text, value: link.url })),
          ],
        },
      ],
    };

    const teamsResponse = await fetch(env.TEAMS_WEBHOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(card),
    });

    if (!teamsResponse.ok) {
      // Relay the status so Orq.ai retries the delivery.
      console.log(`Teams rejected the message: ${teamsResponse.status}`);
      return new Response(`Teams rejected the message: ${teamsResponse.status}`, {
        status: teamsResponse.status,
      });
    }

    console.log(`Forwarded notification ${envelope.id} to Teams (${teamsResponse.status})`);
    return new Response("OK", { status: 200 });
  },
};

function severityColor(severity) {
  switch (severity) {
    case "critical":
      return "B71C1C";
    case "warning":
      return "F57C00";
    case "ok":
      return "2E7D32";
    default:
      return "1565C0";
  }
}

curl --location 'https://api.orq.ai/v2/notifiers' \
--header "Authorization: Bearer $ORQ_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "display_name": "Teams alerts",
    "type": "NOTIFIER_TYPE_WEBHOOK",
    "webhook_url": "https://teams-relay.example.workers.dev"
}'

import { Orq } from "@orq-ai/node";

const orq = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });

const notifier = await orq.notifiers.create({
  displayName: "Teams alerts",
  type: "NOTIFIER_TYPE_WEBHOOK",
  webhookUrl: "https://teams-relay.example.workers.dev",
});

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

notifier = orq.notifiers.create(
    request={
        "display_name": "Teams alerts",
        "type": "NOTIFIER_TYPE_WEBHOOK",
        "webhook_url": "https://teams-relay.example.workers.dev",
    }
)

{
  "id": "ntf_01JQ8Z2K4M6P8R0T2V4X6Z8B0D",
  "version": 1,
  "workspace_id": "ws_01JQ8Z0MB5W1YTVN3GCK7B0EXA",
  "timestamp": "2026-08-08T09:30:00Z",
  "title": "Budget usage has reached your notification threshold",
  "body": "Your usage today for workspace acme has reached $92.00 (92%) of your $100.00 budget. This alert is configured at 90% ($90.00).",
  "severity": "warning",
  "links": [
    { "text": "Manage budgets", "url": "https://my.orq.ai/budgets" }
  ],
  "tags": {
    "budget_id": "bgt_01JQ8Z0MB5W1YTVN3GCK7B0EXA",
    "scope_kind": "WORKSPACE",
    "period": "DAILY",
    "threshold_percent": "90"
  }
}

​

Budget levels and interaction

​

How multiple budgets interact

• Every applicable budget is enforced. A request must pass every budget that matches it. No budget overrides another.
• Each budget tracks its own usage. A request counts toward every budget that applies to it, at the same time.
• The most restrictive budget binds. The effective cap for a dimension is the most restrictive applicable budget. Limits on different dimensions (cost, tokens, requests per minute) all apply simultaneously.
• Requests per minute are enforced per budget, each with its own rolling 60-second window.
• Expired budgets stop enforcing. After the expiration date a budget no longer blocks requests, even though it stays in the list.

​

Worked examples

​

When a limit is exceeded

​

Reset periods

​

See also