Pricing and limits
How Agent API and MCP calls are billed, the per-key rate limits, the daily page quota, and every error code your integration should handle.
How calls are billed
Section titled “How calls are billed”API and MCP calls use the same plan as the Rankability app. There is no separate API balance and no add-on fee: a scan, audit, research job or article started through the API uses your plan exactly as it would in the app.
- Reads are free. Listing, reading and exporting your own data, estimates and deletes cost nothing. They count only toward the rate limit.
- Work draws on your plan. Scans, research, audits, crawls and content use your plan’s usage. Check the impact before you start with
GET /usage/estimate, and check what you have left withGET /usage. - Failed jobs are not charged. Content and research jobs release or refund their usage if they fail before producing a result.
The Usage and allowances guide covers the GET /usage response, reservations and what happens when you run out. Plans and prices are on the pricing page; your current usage and billing are in Settings > Billing.
Pay as you go
Section titled “Pay as you go”Without a plan, you can pay per call with prepaid credits. At list price 1 credit is $0.01; larger credit packs lower the effective price. Reads stay free. New developer accounts start with 300 free credits; create one. On a Rankability plan, calls draw on the plan’s usage instead.
| Operation | Price |
|---|---|
| Google organic check | 10 credits ($0.10) per check |
| Bing check | 10 credits ($0.10) per check |
| DuckDuckGo check | 10 credits ($0.10) per check |
| Local pack check | 10 credits ($0.10) per location check |
| YouTube check | 10 credits ($0.10) per check |
| Brave check | 20 credits ($0.20) per check |
| Brave AI check | 25 credits ($0.25) per check |
| Google AI Overview check | 15 credits ($0.15) per check |
| Google AI Mode check | 15 credits ($0.15) per check |
| Copilot check | 15 credits ($0.15) per check |
| ChatGPT check (web search) | 40 credits ($0.40) per check |
| Perplexity check | 50 credits ($0.50) per check |
| Gemini check | 75 credits ($0.75) per check |
| Claude check | 35 credits ($0.35) per check |
| Grok check | 45 credits ($0.45) per check |
| DeepSeek check | 25 credits ($0.25) per check |
| Meta AI check | 25 credits ($0.25) per check |
| Page scrape | 10 credits ($0.10) per page |
| Site crawl | 10 credits ($0.10) per page |
| Structured extraction | 50 credits ($0.50) per call |
| Page audit | 150 credits ($1.50) per audit |
| Site audit crawl | 1 credit ($0.01) per 5 pages |
| Live rank check | 10 credits ($0.10) per check |
| Domain explorer | 600 credits ($6.00) per job |
| Keyword research | 500 credits ($5.00) per job |
| Keyword research, deep mode (trending, Reddit, YouTube, e-commerce) | 750 credits ($7.50) per job |
| Completed article | 750 credits ($7.50) per completed article |
| Optimization | 400 credits ($4.00) per call |
| Full-document rewrite | 250 credits ($2.50) per call |
| Brief or research only | 150 credits ($1.50) per call |
Price list version api_payg_v2_2026_11_15.
Operations not listed here, such as Serena, white-label reports, the client portal and publishing, need a plan.
Pay-as-you-go limits
Section titled “Pay-as-you-go limits”| Limit | Value |
|---|---|
| Requests per minute, per key | 10 until your first credit purchase, then 60 |
| Requests per day | No daily limit |
| Monthly spend cap | $500 per calendar month (UTC). Set a lower cap on your API & MCP page; contact support for a higher one. |
Spend is credits charged at API prices this month, at list price. When the cap is reached, requests that would start paid work return 402 api_spend_cap_reached with cap_usd, spent_usd and resets_at, and no Retry-After. Reads keep working, so you can still fetch results you already paid for.
Every pay-as-you-go response also carries:
| Header | Meaning |
|---|---|
X-Rankability-Credits-Charged |
Credits this request was charged. Jobs charged when they finish appear in GET /usage/events instead. |
X-Rankability-Credits-Remaining |
Your credit balance after this request |
GET /usage returns your balance in credits and dollars, your rate limit and your spend this month against the cap.
Rate limits
Section titled “Rate limits”Every API key, and every OAuth connection, has its own request limit over a sliding 60-second window. MCP tool calls count against the same limit as direct API calls.
| Product | Plan | Requests per minute, per key | Requests per day |
|---|---|---|---|
| Rankability | Starter (including trials), and earlier Starter and Core Lite plans | 60 | No daily cap |
| Rankability | Growth (including trials), and earlier Core and Growth plans | 120 | No daily cap |
| Rankability | Pro (including trials), and earlier Team, Scale and Agency plans | 240 | No daily cap |
| Rankability | Free | 30 | No daily cap |
| Copywriter plans | Core | 30 | No daily cap |
| Copywriter plans | Scale | 60 | No daily cap |
| Copywriter plans | High-volume | 120 | No daily cap |
| SEO Researcher | Free sample and Starter | 60 | No daily cap |
| SEO Researcher | Pro | 120 | No daily cap |
| SEO Researcher | Agency | 240 | No daily cap |
| SEO Researcher | Scale | 500 | No daily cap |
Your X-RateLimit-Limit response header is authoritative. Every response carries:
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
Requests allowed per minute for this key |
X-RateLimit-Remaining |
Requests left in the current window |
X-RateLimit-Reset |
Seconds until the window resets |
Retry-After |
Seconds to wait, sent with 429 rate_limit_exceeded |
On a 429, wait Retry-After seconds, then retry with the same Idempotency-Key. Spread polling out: every 30 to 60 seconds is enough for long-running jobs.
Daily page quota
Section titled “Daily page quota”Scraping and crawling (POST /scrape, POST /crawl) also have a daily page quota per organization that resets at midnight UTC. Both endpoints return X-Quota-Limit, X-Quota-Used and X-Quota-Remaining, and GET /crawler/usage reports the quota without fetching anything. When it runs out, calls return 429 quota_exceeded. Details are in Authentication and rate limits.
Error codes
Section titled “Error codes”Every error has the same shape:
{ "error": { "code": "rate_limit_exceeded", "message": "Human-readable description of what went wrong", "details": {} }}Branch on code, not on message. The standard codes:
| HTTP | Code | Description |
|---|---|---|
| 400 | invalid_input |
Request body validation failed |
| 400 | invalid_operation |
Operation not valid for current state |
| 401 | unauthorized |
Missing, invalid, expired, or revoked API key |
| 403 | forbidden |
Key lacks required scopes |
| 404 | not_found |
Resource not found or doesn’t belong to your org |
| 409 | conflict |
Resource state conflict (e.g., job already in progress) |
| 409 | already_approved |
Brief already approved |
| 409 | not_ready |
Artifacts not yet available |
| 402 | insufficient_credits |
Not enough credits to run this job |
| 402 | copywriter_allowance_exhausted |
Core completed-outcome allowance has been used for the current period |
| 403 | plan_required |
Active subscription required |
| 403 | plan_limit_exceeded |
Plan limit reached (e.g., max tracking projects) |
| 429 | rate_limit_exceeded |
Too many requests |
| 429 | usage_limit_reached |
Pooled on-demand usage is paused until retry_at; scheduled work remains protected |
| 429 | capacity_reached |
Tracker is too busy to start a scan; retry after Retry-After |
| 429 | concurrency_limit_reached |
Your organization already has the maximum number of these jobs running; retry when one finishes |
| 410 | credit_balance_retired |
This pooled account uses /usage, not a credit balance |
| 503 | service_unavailable |
Queue service unavailable |
Access errors
Section titled “Access errors”Returned before any work starts, when the organization cannot use the API at all:
| HTTP | Code | Meaning |
|---|---|---|
| 403 | subscription_required |
The organization has no active plan. The message tells the user where to reactivate it. |
| 403 | upgrade_required |
The organization’s plan does not include API and MCP access. |
Payment errors
Section titled “Payment errors”| HTTP | Code | Meaning |
|---|---|---|
| 402 | credits_required |
Not enough credits for this call, or no plan and no credits. details carries credits_needed, credits_balance, balance_usd, checkout_url, trial_url and lead_with; message is one sentence an agent can show the user as is. |
| 403 | plan_required |
The tool or endpoint needs a plan. Names the cheapest plan that includes it, with a trial_url. |
| 402 | api_spend_cap_reached |
The account reached its monthly spend cap. details carries cap_usd, spent_usd and resets_at. |
When any of these is returned, show the message to the user and stop. Retrying will not help until they act on it.
More detail, including details fields for each code, is in Errors.
