Budgets

Every project has a budget: a dollar limit, a period it resets on, and a mode that decides what happens at the limit. The mode is the whole game — alert_only tells you, hard_deny stops the spend.

Set a budget

A project's budget lives on its Budget & Alerts tab.

1. Open the project and select Budget & Alerts.
2. Set the limit in USD.
3. Pick the period: daily, weekly, or monthly. On the Free tier, monthly is the only period; daily and weekly unlock on Founder and above.
4. Pick the mode: alert_only or hard_deny.
5. Save. The form tracks unsaved changes — nothing applies until you save.

What happens at the limit

hard_deny blocks the call before it is dispatched. The SDK's pre-flight check comes back denied, the provider is never reached, and your code sees a BudgetExceededError — the same denial the CLI reports as exit code 4. The blocked call is recorded as budget_denied, excluded from spend — it never happened — and surfaced on the Costs tab as blocked-call savings.

alert_only never blocks. Calls proceed past the limit; you get notified. The budget is a tripwire, not a wall.

Every tier can run a hard cap, with one gate: the Free tier allows one hard-deny project. On paid tiers, every project can hard-deny. See Budget enforcement for the SDK's view of a denial.

Per-run caps (SDK v0.3.0+)

Budgets can also cap an individual agent run, not just the project period. Runs are identified by the stable run id the SDK stamps on every pre-flight budget check inside a solwyn.run(...) scope — configure the cap in Cloud, and the SDK enforces it automatically once the scope is open. A per-run denial behaves like any other budget denial: the same BudgetExceededError, the same mode semantics. See Agent runs: per-run budget caps and Budget enforcement for the SDK-side mechanics.

Thresholds — notification, not enforcement

Percent thresholds fire notifications as spend crosses them. They never block anything — enforcement belongs to the mode alone.

Every project starts with a 100%-of-budget email alert armed by default. Add thresholds (1–100%) on the Budget & Alerts tab; the number you can add is tier-capped — one on Free, ten on Founder and Team, unlimited on Scale.

Delivery defaults — the second form on the tab

Below the budget form, the Delivery defaults card sets where this project's notifications go by default: the severity floor, default channels, and which event types deliver. The two forms save independently — saving the budget does not save delivery settings, and each tracks its own unsaved changes.

Old links to a project's separate Alerts or Delivery pages redirect here.

Cross-references

• The SDK raises BudgetExceededError on a denial and reports budget_denied status — see Budget enforcement.
• The CLI's solwyn budget checks, settles, and updates the same budget; denials are exit code 4.
• Alert rules beyond simple thresholds — forecasts, anomalies, the account-wide cap — live on the Alerts page.