Plans & Limits

Surprise limits generate support tickets; documented ones generate upgrades. This page explains how MisarReach limits behave and how to work with them from the API and MCP.

Reading your current limits

Plan allowances differ per account, so read them rather than hard-coding them:

curl https://api.misar.io/reach/billing/usage \
  -H "Authorization: Bearer mrk_your_key"

{ "success": true, "leadsUsed": 82, "leadsLimit": 100, "periodStart": "2026-08-01T00:00:00Z" }

leadsLimit is null when your plan has no numeric cap configured. Your plan and renewal date come from GET /reach/billing/subscription.

Knowing before you're blocked

Poll GET /reach/billing/usage before a large batch — the REST API does not yet return per-call usage headers. When a call does exceed your plan, the error body carries the allowance and the upgrade path:

{ "error": "plan_limit_exceeded", "feature": "leads", "used": 100, "limit": 100, "plan": "free" }

MCP clients read these automatically and print a one-line notice once you pass 80% — a warning while your work is still succeeding, rather than an error afterwards.

What happens when you reach a limit

The call is rejected with a machine-readable body:

{
  "error": "…",
  "code": "plan_limit_exceeded",
  "upgrade": {
    "feature": "<feature>",
    "feature_label": "…",
    "usage": { "used": 100, "limit": 100, "remaining": 0 },
    "current_plan": { "slug": "free", "name": "Free" },
    "plans": [{ "slug": "pro", "name": "Pro", "price": "…", "url": "…" }]
  }
}

Check for code === "plan_limit_exceeded" rather than the HTTP status — that field is stable across products, and the upgrade object carries everything needed to show a user their options.

MCP clients render this as a formatted upgrade card automatically. No handling required.

Raising a limit

Upgrade from your account's billing settings. Upgrades apply instantly to the current period, and you can downgrade at any time with your data left in place.

Rate limits

Separate from plan limits and unrelated to your plan. Exceeding them returns 429 with a Retry-After header and no plan_limit_exceeded code.