---
title: "Pricing and limits"
description: "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."
canonical_url: "https://developers.rankability.com/pricing"
section: "Resources"
last_updated: 2026-11-16
---

# 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

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 with `GET /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](/guides/usage) guide covers the `GET /usage` response, reservations and what happens when you run out. Plans and prices are on the [pricing page](https://www.rankability.com/pricing/); your current usage and billing are in [Settings > Billing](https://app.rankability.com/settings?tab=billing).

## 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](https://app.rankability.com/developer/sign-up). 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

| 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

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

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](/guides/authentication#daily-page-quota-scrape--crawl).

## Error codes

Every error has the same shape:

```json
{
  "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

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

| 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](/guides/errors).
