Limits and budgets
Cap what a workflow run may spend and how long it may take, set per-step limits and rules, and see how workflow limits combine with workspace budgets.
On this page
Limits keep runs predictable. Every workflow has a budget per run, a point where it pauses and asks, a timeout and a cap on concurrent runs. Steps can have tighter limits of their own, and workspace, project, factory, member and agent budgets apply on top. Whatever the source, the promise is the same: “Runs pause and ask at the threshold; nothing is silently stopped.”
Workflow limits
Workflow limits live on the start node, under Limits, below the triggers.
| Field | YAML | Range | What it does |
|---|---|---|---|
| Budget per run | budget_usd | $1–200 | The most one run may spend, in dollars, across model calls and compute |
| Pause and ask at | pause_at_pct | 50–100%, default 80% | When spend reaches this share of the budget, the run pauses at the next step boundary and asks whether to continue |
| Timeout | timeout_min | 5–600 minutes | Wall-clock time for a run, including time waiting on people |
| Concurrent runs | max_concurrent_runs | 1–16 | How many runs of this workflow may go at once. Extra runs queue |
limits:
budget_usd: 8
pause_at_pct: 80
timeout_min: 120
max_concurrent_runs: 4Limits are part of the workflow, so changing them creates a new version like any other edit. Runs in progress keep the limits of the version they started on.
Step limits
Any step can have its own Limits: a budget, a timeout and a number of retries.
- id: implement
kind: agent
name: Implement in isolated worktree
owner: { kind: agent, agent: builder, model: opus-5.5 }
instructions: Implement {{steps.plan.output.summary}}.
limits:
budget_usd: 4
timeout_min: 60
retries: 1A step budget can’t exceed the workflow’s: “Step budget is above the workflow’s $8 cap.” Step retries re-run a step that errored (for example, a crashed runtime); they’re separate from a gate’s On fail attempts, which handle a check that ran and failed. See Gates and failure handling.
What happens at a limit
- At the pause threshold (80% of the budget by default), the run finishes its current step, then pauses. You get an ask: Decide whether it keeps going.
- While paused, the run keeps its worktree, the machine is checkpointed and compute billing stops.
- You choose: Approve once (raise this run’s limit by an amount, once), Raise limit (change the budget for every run it applies to), or Stop run (cancel with a summary of what was done).
A small overdraft lets in-flight model calls finish, so a response is never cut off mid-way. The run header shows Paused by or Bound by with the limit that applies, for example “Paused by the Platform factory’s daily budget”.
A run that hits its Timeout fails with the step it was on. Waiting time counts, so set timeouts with your approval steps in mind, or give Human steps an SLA and an escalation instead.
How limits combine
A run is capped by every limit that applies to it, and the lowest applicable limit wins:
| Limit | Set in |
|---|---|
| Step budget | Step inspector → Limits |
| Workflow budget per run | Start node → Limits |
| Agent budget per run | Agent → Budget & limits |
| Factory day and month budgets | Factory → Guardrails |
| Project budget | Settings → Billing & usage → Budgets & alerts |
| Member budget | Budgets & alerts (plan-dependent) |
| Workspace budget | Budgets & alerts |
| Credit balance | Credits (plus metered overage if enabled) |
The run’s cost meter shows spent / effective limit, and its popover names the binding limit. If a workflow’s budget per run is higher than a parent budget allows, the workflow is still valid, but runs pause at the lower limit.
Budgets in Budgets & alerts have a period (per run, day or month), alert thresholds (such as 50%, 80% and 100%) and an action at 100%: Notify, Pause or Ask. A workflow’s limits appear there as a per-run budget with source “workflow limits”, so they’re never configured twice. See Budgets and alerts and A run was paused by a budget.
Rules
Rules are plain-language constraints a workflow can never break, shown under Rules · things it can never break on the start node. Each rule has text, a scope and an enforcement mode.
| Field | Options |
|---|---|
| Applies to | Every step, or a chosen step |
| Enforce | Instruct: added to every scoped step’s instructions. Check: a judgment check runs after scoped steps. Block: matching actions are denied and logged |
rules:
- text: Never touch infra/prod without the operator agent.
scope: all
enforce: block
- text: Every money movement goes through LedgerGuard.post().
scope: [implement]
enforce: checkInstruct is free and good for conventions. Check costs a judgment call per scoped step and catches violations after the fact; a failed check behaves like a failed gate. Block stops matching actions before they happen and is the right choice for anything irreversible.
Rules sit alongside workspace General instructions (Settings → Guidance & memory) and factory Guardrails. Use guidance for how agents should work everywhere, guardrails for what commands and domains a factory allows, and workflow rules for constraints specific to this workflow.
Choosing values
- Start with a budget per run around twice the cost of a typical run. The factory Report shows Avg cost per step and Cost / PR once you have history, and the New run dialog shows an estimate based on past runs.
- Keep Pause and ask at at 80% unless runs are very predictable.
- Set Concurrent runs to what your CI and reviewers can absorb. Queued runs wait without cost.
Related
- Factories: factory guardrails and budgets
- Usage and budgets API
- Credits and auto-recharge