SOLWYN

Budgets

Limits, periods, alert-only vs hard-deny, thresholds, and what actually happens at the cap.

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 Production 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 — since 2026-09-01 the API itself admits them with a reservation, so the SDK sees an ordinary allow and logs nothing — and you get notified. The budget is a tripwire, not a wall. Past the limit the project's gauge turns red with a BUDGET EXCEEDED badge on the Overview, Projects, and Budget views, with utilization reported past 100%.

What a hard cap bounds

A budget check reserves a call's cost before the provider is called. With Python SDK 0.10.0+ or TypeScript SDK 0.3.0+, the check also carries the call's output bound: the most output tokens the call can produce. Solwyn reserves the call's estimated input cost plus that bound at the output rate of the call's primary model, so a call whose largest possible output does not fit the remaining budget is refused before it runs. On a hard_deny admission, the SDK sends an uncapped request with a default cap (4096 tokens unless you configure another), and refuses locally a request whose output it cannot bound. When the call settles, Solwyn charges its actual cost and releases the rest. Calls admitted in alert_only mode are unchanged.

The bound limits output tokens; the reservation is still an estimate in dollars, so a call can settle above it:

  • Failover to a more expensive model. Admission prices the primary model, and settlement prices the model that actually served the call. If a fallback hop on a pricier model serves it, the call can spend more than it reserved even though its output stays within the bound. On a tight cap, keep fallbacks no more expensive than the primary.
  • Estimated input. The SDK estimates input tokens from text length, so the input half of the reservation can be low.
  • Surfaces the SDK does not bound. Unmetered surfaces have no budget check at all, and the Python SDK's OpenAI decisions.create is checked but never capped. See What hard_deny bounds (Python) or TypeScript SDK budgets.

Older SDKs send no output bound. Solwyn then prices the call's output as equal to its input, so later calls are refused once the cap is reached, but one large call can still overshoot it.

Effective mode

The mode on a budget check response is the effective mode for that call, not only the project setting. It is hard_deny whenever any enforcing cap applies: a hard_deny project, or, on an alert_only project, a hard-deny scoped rule or a hard per-run cap that matches the call. This holds on allowed checks as well as denials, so the SDKs bound the output of every call a hard cap governs, and an alert_only project can see hard-deny behavior (an added output cap, or a local refusal) on the calls such a rule applies to.

Refusal alerts

When a call is refused because it would take the project past its limit, your 100% alert rule fires and reports actual spend and the refused call's estimate separately. Spend never includes the refused amount, because the call never ran. Every channel shows the two figures, for example "Spend so far: $0.40 (limit: $1.00). Refused call estimate: $5.00." Slack, Teams, Discord, Telegram and PagerDuty title the alert "Call refused at budget limit", and SMS reads "project call refused at budget limit". Slack, Teams, Discord, Telegram and email also say the call was refused before it ran, so it added nothing to spend; SMS and PagerDuty leave that sentence out.

The webhook payload's data carries the same split: current_usage is the actual spend, and refused_call_estimate_usd is the refused call's estimate. refused_call_estimate_usd is present on refusal alerts only, so use it to tell a refusal apart. mode is set on refusal alerts too, but it also appears on other alerts, such as scoped-budget alerts (including alert_only crossings), so it does not identify a refusal.

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 carries on every admission inside a solwyn.run(...) scope — configure the cap in Cloud, and the SDK enforces it automatically once the scope is open. (From SDK v0.4.0 a token-billed run draws on a budget lease rather than checking before every call; the cap is enforced the same way, just without the per-call round-trip.) A per-run denial behaves like any other budget denial: the same BudgetExceededError (with budget_period="agent_run"), the same mode semantics. See Agent runs: per-run budget caps and Budget enforcement for the SDK-side mechanics.

Runaway-run rules

A runaway run rule is a wildcard per-run cap: it applies to every run in the project rather than one named run id. Create one from the Budget & Alerts tab (or as a runaway_run entry in the budget's thresholds) with:

  • a run spend cap in USD (whole cents, greater than zero, at most $1,999,999.99);
  • optionally a call threshold and a window of 1–1440 minutes — both or neither — that flag a run making too many calls too fast;
  • a mode: alert_only (the default) notifies when a run crosses the cap; hard_deny makes the cap enforceable, so a run at its cap is denied further calls with denied_by_period: "agent_run". A hard-deny runaway rule is authoritative on its own — it denies even on an alert_only project, and the SDK sees mode: "hard_deny" on that denial.

A runaway-run rule denies calls; it does not stop the run. Stopping is an operator action — see below. Each rule fires at most once per run per UTC day, and a firing shows a Stop run button in the alert sidebar.

Scoped budgets

SDK v0.5.0+. A scoped_budget rule caps one slice of a project's spend on the project's period — one model, one provider, one agent run (by the raw id your code saw), or one exact tag pair. Add one from the Budget & Alerts tab, or as an entry in the thresholds array of PUT /api/v1/projects/{project_id}/budget:

{
  "type": "scoped_budget",
  "scope": "tag",
  "match": "customer_tier",
  "match_value": "enterprise",
  "limit": 50.0,
  "mode": "hard_deny",
  "channel_ids": []
}

match is the selector — a model id, a provider name, a run id, or (for tag) the tag key, in which case match_value is the tag value and is required; it is invalid for the other scopes. limit is in USD at micro-dollar precision. Each scoped rule carries its own mode: a hard_deny scoped rule denies matching calls even when the project's mode is alert_only, and the SDK reports the denial with budget_period set to the scope ("model", "provider", "agent_run", "tag"). A tag rule can only deny a call that carries the tag — the SDK sends its merged tag snapshot on every budget check for exactly this reason — and a tag denial is never sticky. The rule's response carries its live current_usage, or null when it is temporarily unavailable. One selector may hold one limit.

Stopping a run

A stop is different from a cap. Stop on a run in the project's Agents tab denies every future budget check for that run and revokes its leases; the SDK raises RunStoppedError on the run's next call, and the stop cannot be undone for that run id. Caps are budget decisions the mode can soften; a stop is not.

Thresholds — notification, not enforcement

Percent thresholds fire notifications as spend crosses them. They never block anything — enforcement belongs to the project mode, and to the per-rule mode of a scoped or runaway-run entry.

Every project starts with a 100%-of-budget email alert armed by default. Add thresholds (1–100%) on the Budget & Alerts tab; the number of rules a project can hold is tier-capped — one on Free, ten on Production and Team, unlimited on Scale — with a hard payload cap of fifty entries.

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 a budget_denied denial receipt — see Budget enforcement. A denied call still counts toward the Free tier's monthly request quota.
  • A stopped run raises RunStoppedError instead — see Run control and Agent runs.
  • 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.

On this page