Budgets and alerts

Limits on AI spend per organization, customer, feature, user or project, with alerts at 50, 80 and 100 percent and SDK enforcement that stops calls before they are made.

Two kinds of budget

	SDK budget	Cloud budget
Set with	`veqen.budget(...)` in code	The Budgets page, the MCP `set_budget` tool
Counts spend	In this process	Across every process sending to your organization
Enforced	Before a wrapped call, using recorded spend	After ingestion, budget evaluation and SDK polling (every 30 seconds by default)
Alerts	–	Email, Slack and webhook at 50%, 80% and 100%

Use both: SDK budgets check spend in one process; cloud budgets combine the usage received across your organization. Neither guarantees a spending cap. A call can cross the limit before its cost is recorded, and concurrent or in-flight calls can add more spend. Local counters reset when the process restarts. Delayed or failed ingestion and polling delay cloud enforcement; SDKs retain their last known cloud state when polling fails.

Scopes

Scope	Value	Meaning
Organization	–	All spend
Customer	`*`	Every customer gets the limit separately
Customer	`acme`	Only Acme
Feature	`*` or a name	Per feature
User	`*` or an id	Per end user, the usual guard for free plans
Project	`*` or a name	Per team, program, pipeline or cost center

Periods are calendar months or days, in UTC. Calls without the tag in question don't count toward a * budget for that tag.

Modes

Alert: notifies at 50%, 80% and 100%. Calls continue.
Block: also lists the value as breached at 100%. Every SDK using your key then raises BudgetExceeded for calls with that tag, before the request is sent, until the period resets or you raise the limit.

try:
    client.responses.create(model="gpt-5-mini", input=prompt)
except veqen.BudgetExceeded as exc:
    return f"You've used this month's AI allowance (${exc.limit_usd:.2f}). Upgrade for more."

try {
  await client.responses.create({ model: "gpt-5-mini", input: prompt });
} catch (error) {
  if (error instanceof BudgetExceeded) return upgradePrompt(error.limitUsd);
  throw error;
}

Spend that arrives through OpenTelemetry or record() counts toward budgets, but only the SDK wrappers can stop a call before it happens.

Where alerts go

Owners and admins get email. On Pro and Team, add a Slack incoming webhook and a signed webhook under Settings › Alerts. Webhook bodies look like:

{"type": "budget.threshold", "org_id": 42, "subject": "Budget Free users at 80%",
 "text": "Spent this month, of $5.00: customer acme: $4.00.",
 "data": {"budget_id": 7, "scope": "customer", "limit_usd": 5.0, "threshold": 80, "blocking": false,
          "crossed": [{"value": "acme", "spent_usd": 4.0}]},
 "url": "https://veqen-app.com/app/budgets"}

Each alert is sent once; a failed delivery is logged, not retried. Verify the Veqen-Signature: t=<unix>,v1=<hex> header: compute HMAC-SHA256 of <t>.<raw body> with your webhook secret and compare in constant time.

The same channels carry spend-spike alerts (a day at twice the previous week's average and over $25), credit-expiry warnings, connection failures and the Monday digest.