Workspace Budgets & Billing Enforcement

ToothFairyAI splits spend control across two layers: an account-level billing profile (credit balance, auto-recharge, monthly spend cap — managed from your profile) and a per-workspace budget that administrators allocate. This page covers the admin side: where budgets are set, how they are enforced, and best practices for sub-workspaces.

Menu location

The budget is set from: Admin → General settings → Budget allocation per workspace

The two budget layers

	Account level (Profile → Billing)	Workspace level (this page)
Control	Credit balance, auto-recharge, monthly spend cap in USD	Budget allocation in UoI
Scope	Every workspace you own	One workspace family (root + children)
Managed by	The account owner, personally	Workspace Root / Super Admin
Effect when reached	All owned workspaces pause	That workspace family pauses

Both layers must have headroom for agents to run: consumption stops when the credit balance hits $0, the account spend cap is reached, or the workspace family budget is exhausted — whichever comes first.

Budget allocation per workspace

The Budget allocation slider in the workspace settings sets how much usage the workspace (and its children) can consume per billing cycle.

• The slider moves in blocks of UoI — 5,000 UoI per block on Serverless, 7,500 UoI per block on Enterprise (1 UoI = $0.01, so one Serverless block = $50 of usage headroom).
• The default allocation for a new workspace is 5 blocks = 25,000 UoI.
• The maximum allocation is 100M UoI (equivalent to $1,000,000 of usage).
• Enterprise workspaces can alternatively set a custom UoI budget — arranged with your account team, along with reserved compute allocations.

Raising the budget re-enables usage immediately

If a workspace was paused because its budget was exhausted, increasing the allocation resumes it right away — no need to wait for the next cycle.

Budget is not seats

The allocation is measured in UoI blocks, not people. There are no per-seat licence fees — unlimited users can be invited to the workspace. The budget caps consumption, never headcount.

How enforcement works

The platform runs a consumption watcher that continuously reconciles usage, debits your credit balance, and pauses or resumes workspaces:

1. Debit — Usage across a workspace family is totalled in UoI and debited from the account credit balance.
2. Auto-recharge — If the balance is at or below the auto-recharge threshold, a top-up is attempted first (only if auto-recharge is enabled and a payment method is on file).
3. Pause — A workspace family is paused when any of these is true:
   • the credit balance is $0 or less
   • the family's consumption has reached its budget
   • the account monthly spend cap has been hit
4. Cascade — Pausing a root workspace pauses all of its child workspaces too.

Resume behaviour

The cause of the pause determines when it lifts:

Pause cause	Resumes when
No credit (balance ≤ $0)	As soon as the balance is topped up again — even mid-cycle
Family budget exhausted	The budget is raised, or a new billing cycle starts
Account spend cap hit	The cap is raised/removed, or a new billing cycle starts

30-day billing cycles

The consumption cycle is a fixed 30-day window anchored per workspace — not a calendar month. Budget and cap resets follow that window.

Sub-workspaces & centralised billing

Child workspaces mirror your organisation — dev, stage, prod, or departments — under a single root. Full details in Workspace Hierarchy; the billing-relevant rules:

• One bill — All consumption across child workspaces is billed to the root workspace's payment profile.
• Inheritance — Children inherit the root's plan and budget allocation. Plan and billing fields are not editable on a child; change them at the root.
• Shared budget — The root's budget covers the whole family: the root and every child draw from the same allocation.
• One level deep — A child cannot have children of its own.
• Limits — Serverless roots can have up to 5 children, Enterprise up to 15.
• Cascade deletion — Deleting a root deletes all of its children. Pausing a root pauses all of its children.

Best practices for sub-workspaces

• Mirror environments, not people — Create dev / stage / prod children (or departments) rather than one workspace per team of users; users are unlimited and free, so organise by consumption boundary instead.
• Keep production on its own root — A separate root for production gives it an independent budget family, so a runaway dev agent can never pause production by exhausting a shared budget.
• Budget non-prod conservatively — Allocate the minimum blocks to dev/stage workspaces and raise on demand; raising the budget resumes usage instantly.
• Set the account cap as the outer rail — Even with per-workspace budgets, set an account monthly spend cap so a misconfigured budget can never overspend the account.

Troubleshooting a paused workspace

If a workspace shows as paused or agents stop responding, check in this order:

1. Credit balance — Profile → Billing. Balance at $0 pauses everything; recharge to resume immediately.
2. Workspace budget — Admin → General settings → Budget allocation. If the family's consumption reached the budget, raise the allocation to resume.
3. Account spend cap — Profile → Billing → Credits & limits. If the cap was hit, every workspace you own is paused; raise the cap or wait for the cycle to reset.

tip

Use the usage dashboard to see which workspaces and services are consuming the budget, month by month.

Related pages

• Billing, Credits & Spend Limits — the account-level billing profile
• Units of Intelligence (UoI) pricing — what a UoI covers
• Workspace hierarchy — creating and managing child workspaces