Set budgets and spending alerts

Cap spend for the workspace, a project, factory, workflow, agent or member, get alerts at thresholds, and choose what happens at the limit.

On this page

A budget is a spending limit for part of your workspace over a period of time. Budgets are separate from your credit balance: credits pay for usage, budgets decide how much of it is allowed. When a budget is reached, runs pause and ask. Nothing is stopped mid-step.

What a budget covers

Applies toCovers
WorkspaceEverything in the workspace
ProjectRuns in one project
FactoryRuns through one factory
WorkflowOne workflow’s runs
AgentOne agent, across factories
MemberRuns a person starts (Business plan)

Each budget has a period: Per run, Daily or Monthly. A per-run budget limits each run on its own; daily and monthly budgets add up every run in scope.

Create a budget

  1. Open Settings → Billing & usage → Budgets & alerts and click New budget. You can also start from a factory’s Guardrails tab, a project, or a run’s cost meter with Set a budget…; the scope is filled in for you.
  2. Choose what it Applies to, then pick the project, factory, workflow, agent or member.
  3. Pick the Period and set the limit in dollars.
  4. Choose when to be alerted under Alert at, for example 50%, 80% and 100%, or add a custom percentage.
  5. Choose what happens At 100%: Notify only, Pause runs, or Pause and ask.
  6. Pick who gets alerts, then click Create budget. A preview shows how the budget would have played out last month.

Admins can create any budget. Factory admins can set budgets for their own factory, up to the limits above it.

What the actions do at 100%

  • Notify only sends the alert. Runs keep going.
  • Pause runs holds new runs in that scope with Waiting · budget, and running runs pause at their next step boundary.
  • Pause and ask does the same, and puts an ask in the Inbox for each held run so someone can decide.

A paused run keeps its worktree and stops machine time, so it costs nothing while it waits and picks up where it left off.

Recover a held run

From the Inbox ask or the run’s cost meter:

  • Approve +$X once raises the limit for that run only.
  • Raise limit… edits the budget. Every run it held resumes.
  • Wait for reset lets the run resume on its own when the period resets.
  • Stop run cancels it with a summary.

For a step-by-step guide, see A budget paused my run.

Alerts

Alerts go to the Inbox and email of the people the budget notifies. Each person can also choose channels in Settings → Notifications under Spend and billing. To send alerts to your own systems, subscribe a webhook to the budget.threshold event.

Workflow limits are budgets too

Each workflow has its own Limits: a budget per run, a “pause and ask” threshold, a timeout and a cap on concurrent runs. They appear in Budgets & alerts with the source Workflow. Editing one there writes a new workflow version; runs in progress keep theirs. See Limits and budgets for the details.

    Type to search the docs, help center and blog.