Plans and rate limits

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:

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.

curl https://api.boltclaw.ai/v1/usage \
  -H "Authorization: Bearer bc_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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.

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. The page endpoints, the social endpoints and the MCP server all draw on the same allowance. Every response carries the current state:

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:

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.