puras

Budgets & spend alerts

Cap spend over a window — per workspace, per skillpack, or per skill — and get alerted before you hit the limit. Enforcing budgets block new runs at the cap; soft budgets only alert.

Your wallet is a single hard floor: a run is rejected once your credit balance hits zero. Budgets are finer-grained spend controls you set yourself — cap spend over a window, scoped to the whole workspace or one skill, with an optional early alert. They're evaluated at enqueue, against the spend of your succeeded jobs in the window.

Manage them in the dashboard under Budgets (in the workspace menu), or via the /v1/budgets API.

What a budget has

FieldMeaning
Scopeworkspace (all your spend) or skillpack (one skillpack, optionally narrowed to a single skill_name).
Windowday, month, rolling30 (last 30 days), or total (all-time).
LimitThe spend ceiling for the window, in USD.
Alert %Optional. Fire an alarm once spend crosses this percent of the limit (e.g. 80).
Enforcetrue blocks new runs once the limit is reached; false is a soft budget that only alerts.

How enforcement works

  • When you submit a job (or start an eval suite), every enabled budget that matches the job's scope is checked. If an enforcing budget's window spend is at or over its limit, the run is rejected with 402 Payment Required and a message naming the budget.
  • Spend is summed from your succeeded jobs in the window — the same runs that debit your wallet. Failed/cancelled jobs cost nothing and don't count.
  • A budget never blocks a run that's still within limit; alarms are best-effort and never get in the way.

Alerts

If a budget sets Alert %, an alarm fires once spend crosses that threshold — once per window period (a new day / month re-arms it; rolling/all-time fire a single alarm). Alarms are emitted as product events you can route to email or Slack via your analytics integration.

In the dashboard each budget shows a live progress bar: green under the alert threshold, amber once alerting, red once over the limit.

API

bash
# Create a $25 / month workspace cap that alerts at 80% and blocks at 100%.
curl -X POST $PURAS_API_BASE/v1/budgets \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Monthly cap","scope":"workspace","period":"month",
       "limit_micros":25000000,"alert_pct":80,"enforce":true}'

# A soft daily alert on one skill (no block).
curl -X POST $PURAS_API_BASE/v1/budgets \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Ads skill watch","scope":"skillpack","skillpack_id":"<id>",
       "skill_name":"google-ads","period":"day","limit_micros":5000000,
       "alert_pct":75,"enforce":false}'

curl $PURAS_API_BASE/v1/budgets -H "Authorization: Bearer $TOKEN"   # list + live status

Limits are in micros (1_000_000 = $1). GET /v1/budgets returns each budget with a status of spent / limit / remaining / pct.

  • Per-run cost cap (MAX_JOB_COST_MICROS) stops a single run before it overshoots — orthogonal to budgets, which span many runs over a window.
  • Per-tool limits in a skill's skill.yaml (tool_limits) guard against a runaway tool loop within a run. See the skill.yaml reference.