Usage Limits and Enforcement

Every AACWorkflow plan includes limits on how many agents, squads, autopilots, and workspaces you can create. When you hit a limit, AACWorkflow prevents you from creating more resources and shows you an upgrade prompt.

Plan limits by tier

These limits apply per account. If you're the owner of an account, the limits apply to all workspaces you create.

What happens when you hit a limit

When you try to create a resource and you've reached the limit:

1. The create request returns an error
2. You see an upgrade prompt in the UI
3. The resource is not created

Example: You're on a Free plan with 5 agents, and you try to create a 6th agent.

{
  "error": "quota_exceeded",
  "kind": "agents",
  "limit": 5,
  "current": 5,
  "plan": "free"
}

Response: 402 Payment Required

The UI shows:

You've reached the agent limit for your Free plan (5 agents).
To create more agents, upgrade to Business or Enterprise.
[Upgrade Now]

Checking your current usage

View your current resource usage in Settings → Billing → Usage:

• Agents created vs. limit
• Squads created vs. limit
• Autopilots created vs. limit
• Workspaces created vs. limit

The UI shows a progress bar for each resource type and warns you before you hit the limit.

Soft-deleted resources

Resources that are archived or deleted (soft-deleted) do not count against your limit. You can delete and recreate resources to stay within your plan.

For example:

• You have 5 agents (Free plan max)
• You archive 2 agents
• Now you can create 2 new agents (you're using 3)

Soft deletes are permanent for quota purposes — you cannot restore archived resources to reclaim quota.

Upgrading your plan

When you hit a limit:

1. Click the Upgrade Now button in the error prompt (or go to Settings → Billing → Plans)
2. Choose a higher plan (Business or Enterprise)
3. Complete the upgrade
4. New resources become available immediately

Limits increase instantly when your upgrade completes — no delay or waiting.

Workspace limits (account-level)

The workspace limit is per account (applies to the account owner):

• Free plan: 1 workspace
• Business plan: 10 workspaces
• Enterprise plan: Unlimited workspaces

If you're on the Free plan and want to create a second workspace, you must upgrade to Business.

Understanding your plan

To see your current plan and limits:

1. Go to Settings → Billing
2. See your current plan (Free, Business, or Enterprise)
3. Click View Details to see limits for each resource type

You can also see the plan pricing page at /pricing for an overview of all plans.

Enforcement and billing integration

Plan limits are enforced by the AACWorkflow server when you attempt to create a resource. The enforcement checks:

1. Your current plan (from billing service)
2. Your current resource count (from the database)
3. Whether creating one more resource would exceed the limit

If it would, the request is rejected with 402 Payment Required.

Fail-open behavior

If the billing service is temporarily unavailable:

• AACWorkflow uses fail-open behavior — limits are treated as unlimited
• You can still create resources
• Once billing is back, normal limits are re-enforced

This ensures that a billing outage doesn't freeze your team's productivity.

Monitoring limit usage

To avoid hitting limits unexpectedly:

1. Set up alerts (via your account manager) for when you're approaching limits
2. Review your resource usage monthly in Settings → Billing → Usage
3. Archive unused resources to free up quota if you're close to your limit
4. Plan your team growth and upgrade before you hit limits

API and automation

When using the AACWorkflow API to create resources:

• Same limits apply
• Same 402 quota_exceeded error is returned on failure
• Parse the error response to show users an upgrade prompt

Example error handling (TypeScript):

try {
  await createAgent({ name: "new-agent" });
} catch (error) {
  if (error.code === "quota_exceeded") {
    console.log(`Limit: ${error.limit}, Current: ${error.current}`);
    showUpgradeDialog();
  }
}

Plan limit guarantees

• No silent failures — if you hit a limit, you get a clear error, not a crash
• Immediate effect — limits take effect when your plan is active
• Accuracy — limits are checked at the moment of creation, so there's no race condition
• Fair to all teams — limits are per-workspace and per-account, not shared

Frequently asked questions

Q: Can I exceed my plan limit if I use the API directly?

A: No. Limits are enforced at the server level, regardless of whether you use the UI or API.

Q: Do archived agents count against my limit?

A: No. Archived resources are soft-deleted and don't count toward your limit.

Q: What happens if I downgrade my plan?

A: If you have more resources than your new plan allows, you'll be at or over the limit. You'll need to delete or archive resources before creating new ones. (Existing resources are never deleted on downgrade.)

Q: Can my account manager increase limits manually?

A: For Enterprise customers, yes. Contact your account manager to request a custom limit adjustment.

Q: Is there a grace period after upgrading?

A: No. Limits take effect immediately when your plan upgrade completes.

Next steps

• Enterprise governance features — budget controls and more
• Billing — manage your subscription and payment method
• Pricing — see all available plans and pricing