# Plans and rate limits A plan changes volume, never capability. Here are the numbers, and the headers that tell you where you are. A plan changes **volume only**. Every capability in this API is available on every plan — pages and links, themes, conversations, analytics, keys, social posting, the social inbox, automations, leads and the MCP server. What differs is how much of each: | | Free | Creator | Pro | Business | |---|---|---|---|---| | Pages | 5 | 20 | 100 | 500 | | Connected social accounts | 30 | 75 | 250 | 1000 | | Posts per month (per account posted to) | 1000 | Unlimited | Unlimited | Unlimited | | Automated DMs per month | 1000 | 25000 | Unlimited | Unlimited | | Leads per month | 100 | Unlimited | Unlimited | Unlimited | | Automations | 1000 | Unlimited | Unlimited | Unlimited | | **API requests per minute, per key** | 20 | 60 | 120 | 600 | | **Active API keys, per workspace** | 5 | 10 | 20 | 20 | Monthly allowances reset on the 1st of each calendar month, UTC. Free accounts may connect every network except X, which needs a paid plan because it charges us for every call. Until the paid plans are next reviewed, no paid plan is below Free on any allowance: where a paid plan's own number would be lower, Free's applies, and the table above shows the number that applies. `GET /v1/usage` returns the numbers that apply to your account right now, including any we have raised for it, and the field sizes and hourly budgets below as well. **Read the allowances that apply right now** — answers `200` Including any we have raised for this organisation, which is why reading them beats hardcoding the table above. ```bash curl https://api.boltclaw.ai/v1/usage \ -H "Authorization: Bearer bc_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` ```js const res = await fetch("https://api.boltclaw.ai/v1/usage", { headers: { Authorization: `Bearer ${process.env.BOLTCLAW_KEY}`, }, }); // 200 const data = await res.json(); ``` An allowance that is used up answers **`402` with `code: "PLAN_LIMIT"`**, and the `error` sentence names the allowance. Hard caps lead with a token you can match on if you keep the body and drop the code: `PAGE_LIMIT_REACHED`, `PUBLISH_LIMIT_REACHED`, `SOCIAL_ACCOUNT_LIMIT_REACHED`, `NETWORK_NOT_IN_PLAN`, `AUTOMATION_LIMIT_REACHED`. A page's own sizes are limits of the same kind: a title of 120 characters, a bio of 600, a link label of 120, a contact note of 300, 12 social icons, and 1,000 links (a safety ceiling: links are unlimited in practice). They are the same on every plan today. A write past one answers `400` naming the field and the number (`409` for a link past the ceiling), and a page saved before a number was lowered keeps what it has. **Nothing is taken away on a downgrade.** An account over an allowance keeps every page, account, automation and post it has; what stops is adding more. Platform costs are separate from the plan — see [Platform charges](https://boltclaw.ai/docs/api/usage#platform-charges). ## Pages per account `POST /v1/pages` past the plan's page allowance answers **`402` with `code: "PLAN_LIMIT"`**, not `409`. The distinction is worth acting on in a client: a `409` means try a different slug, a `402` means no slug will work until the account changes. The `error` sentence names the current allowance. Setting `published: true` on a page can also answer `402` for the same reason — the count of *live* pages is capped by the same number. This is what an account whose subscription has lapsed sees: **nothing is deleted and nothing goes offline**, every page that was live stays live and stays editable through this API, but creating another and switching an unpublished one on both stop until the account is back under its allowance. ## Rate limits **Your plan's allowance per minute, per key** — 20, 60, 120 or 600; see [Plans and rate limits](https://boltclaw.ai/docs/rate-limits). The page endpoints, the social endpoints and the MCP server all draw on the same allowance. Every response carries the current state: | Header | | |---|---| | `X-RateLimit-Limit` | Your plan's requests per minute, e.g. `120` | | `X-RateLimit-Remaining` | Requests left in this window | | `X-RateLimit-Reset` | Unix timestamp when the window resets | A `429` also carries `Retry-After`, in seconds. Wait that long; do not retry immediately. The window is fixed, not sliding: it resets at `X-RateLimit-Reset` and your full allowance is available again. The limit is per **key**, not per account, so an account holding several keys has a correspondingly higher total. Two endpoints are metered separately and more tightly: | Endpoint | Limit | |---|---| | `POST /v1/pages` | 10 per hour, per key, by default — see [A note on 404](https://boltclaw.ai/docs/errors#a-note-on-404) | | everything else | your plan's allowance per minute, per key | `POST /v1/inquiries/{id}/messages` draws from a third bucket: **60 messages per hour per key** by default, in addition to the per-minute allowance. Sending words to a real person is not the same kind of request as reading a page, and the default allowance would let one key put 170,000 messages into somebody's inbox in a day. A single conversation is capped more tightly still, at 30 messages an hour from one sender, the same number the dashboard is held to — a `429` on a busy thread does not mean your key is exhausted. All three numbers are set per plan, and `GET /v1/usage` returns yours as `api_pages_created_per_hour`, `api_messages_per_hour` and `thread_messages_per_hour`. If you are polling `/v1/inquiries` for new messages, once every ten seconds is comfortably inside the limit and is far more often than most inboxes need.