Spend Caps#

Spend caps protect you from unexpected overage charges. Every account has a platform-enforced monthly spend cap based on their tier. You can set an additional custom cap below the platform ceiling.

How spend caps work#

A spend cap is a maximum monthly spend limit in dollars. When your month-to-date spend (subscription + overages) approaches or exceeds the cap, the system:

1. Issues a warning — a cap_hit billing event is created and you receive a notification
2. Waits 15 minutes — the grace period gives you time to raise your cap if needed
3. Pauses your instance — if still at cap after 15 minutes, your substrate is paused and API access is suspended until your cap is raised or the month resets

The 15-minute grace period means your AI's current session is not immediately interrupted when you hit the cap — it has time to finish critical operations before the pause takes effect.

Platform ceilings#

Each tier has a maximum monthly cap that cannot be exceeded:

These ceilings exist to prevent runaway automation from producing unbounded charges. They cannot be removed.

Viewing your current cap#

Go to Dashboard → Billing → Spend Caps. You will see:

• Your current monthly cap and the platform ceiling for your tier
• Whether you are currently at cap
• How much you have spent this month

Setting a custom cap#

You can set a cap below the platform ceiling if you want tighter control:

1. Go to Dashboard → Billing → Spend Caps → Set Cap
2. Enter a limit in dollars — must be between $0 and the platform ceiling
3. Save

Your custom cap takes effect immediately. If your current spend is already above your new cap, the system will start the 15-minute grace period immediately.

Adjusting a cap#

Raising your cap: You can raise your cap up to the platform ceiling at any time. Changes take effect immediately — if your instance was paused due to cap, it resumes within 30 seconds of raising the cap.

Lowering your cap: You can lower your cap at any time. If your current spend is already above the new lower cap, the grace period begins immediately.

Removing your cap: You cannot remove the platform-enforced cap. However, you can set it to the ceiling (the maximum allowed value) to maximise your effective limit. If you set an optional custom cap, you can delete it — custom caps are deletable, platform caps are not.

What counts toward the cap#

The spend cap covers:

• Your monthly subscription fee (Starter: $3, Solo: $9, Professional: $29, Team: $79)
• Atom overage charges ($0.001 per atom above tier limit per month)

The subscription fee alone may constitute most of your cap on lower tiers. For example, on Starter the subscription is $3 and the ceiling is $5 — you have $2 of headroom for overages before hitting the ceiling.

During a cap pause#

When your instance is paused due to a spend cap:

• All API requests return 503 Service Unavailable
• MCP tool calls fail with a cap_paused error
• Your atoms are safe — nothing is deleted during a pause
• Raise your cap (or wait for the monthly reset) to resume

Monthly reset#

Spend caps reset at the start of your billing cycle (the same date each month as your subscription renewal). If your instance is paused due to cap, it automatically resumes at the start of the new billing cycle.

Spend cap vs balance exhaustion#

There are two separate mechanisms that can pause your instance, and they work differently:

Spend cap pause — triggered when your month-to-date spend reaches the cap. You get a 15-minute grace period before instances are paused. This protects against runaway overage charges.

Balance exhaustion pause — triggered when your account balance reaches zero. This is immediate with no grace period. If your balance hits zero while instances are running, they are paused right away. To resume, add credits to your account.

If both conditions are true simultaneously (zero balance and at cap), the balance exhaustion takes priority and instances are paused immediately.

Warning notifications#

To help you stay ahead of pauses, the system sends two levels of balance warnings:

• Low balance warning — sent when your balance would cover less than 1 hour of usage at your current burn rate
• Urgent warning — sent when your balance would cover less than 5 minutes of usage

Each warning type is sent at most once every 2 hours to avoid flooding your inbox. If you receive an urgent warning, update your payment method or add credits promptly to avoid an immediate pause.

Practical examples#

Starter ($3 subscription, $5 ceiling): You have $2 of headroom for overages. At $0.001 per excess atom, that covers 2,000 atoms above your tier limit before hitting the ceiling.

Solo ($9 subscription, $15 ceiling): You have $6 of headroom — enough for 6,000 excess atoms before hitting the ceiling.

Professional ($29 subscription, $50 ceiling): $21 of headroom covers 21,000 excess atoms.

If you consistently approach your ceiling, consider upgrading to a tier with both higher atom limits (reducing overages) and a higher ceiling.