> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Limits

> Agent limits per plan and what happens when you reach them

Each MeshAI plan includes a maximum number of active agents. An **active agent** is any agent that sent at least one heartbeat or telemetry event during the current billing period.

## Limits by Plan

| Plan            | Agent Limit | Audit Retention | Compliance Exports | OTLP Ingest                                                  |
| --------------- | ----------- | --------------- | ------------------ | ------------------------------------------------------------ |
| Free            | 1           | 7 days          | Unavailable        | Rate-limited (default: 300 spans/min sustained, burst 1,500) |
| Starter         | 25          | 90 days         | Unavailable        | Unlimited                                                    |
| Professional    | 100         | 395 days        | Yes                | Unlimited                                                    |
| Enterprise      | Unlimited   | Unlimited       | Yes                | Unlimited                                                    |
| Enterprise Plus | Unlimited   | Unlimited       | Yes                | Unlimited                                                    |

## What Happens When You Hit the Limit

When you reach your plan's agent limit:

1. **Existing agents continue working** - monitoring, policies, and proxy routing are unaffected for already-registered agents.
2. **New registrations are blocked** - attempts to register a new agent return a `402` error:

```json theme={null}
{
  "success": false,
  "error": "Agent limit reached. Your Starter plan allows 25 agents. Upgrade to register more.",
  "current_count": 25,
  "plan_limit": 25,
  "upgrade_url": "https://app.meshai.dev/settings"
}
```

3. **Dashboard notification** - a banner appears in the dashboard when you're at 80% and 100% of your limit.

## Checking Your Usage

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/billing \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  from meshai import MeshAI

  client = MeshAI(api_key="msh_...")
  billing = client.get_billing_info()
  # billing["active_agents"] → 23
  # billing["agent_limit"] → 25
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "plan": "starter",
      "active_agents": 23,
      "agent_limit": 25,
      "billing_period_start": "2026-03-01T00:00:00Z",
      "billing_period_end": "2026-03-31T23:59:59Z",
      "monthly_cost_usd": 299.00
    }
  }
  ```
</ResponseExample>

## How to Upgrade

<Steps>
  <Step title="Go to Billing settings">
    Navigate to [app.meshai.dev/settings](https://app.meshai.dev/settings).
  </Step>

  <Step title="Select a plan">
    Choose the plan that fits your agent count. The prorated difference is charged immediately.
  </Step>

  <Step title="Confirm">
    Your new limit takes effect immediately. You can register additional agents right away.
  </Step>
</Steps>

You can also upgrade programmatically:

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/billing/checkout \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "professional" }'
```

## Deactivating Agents

If you don't want to upgrade, you can free up slots by deleting agents you no longer need:

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Deleted agents are removed from your active count immediately but remain in the audit trail for compliance purposes.