---
title: "Rate Limits & Quotas"
description: "Your subscription controls API key quotas, hourly rate limits, and result sizes. Limits are evaluated live on every request."
canonical_url: "https://scholarxiv.com/developers/docs/papers-api/limits"
markdown_url: "https://scholarxiv.com/developers/docs/papers-api/limits.md"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

---
title: 'Rate Limits & Quotas'
description: 'Your subscription controls API key quotas, hourly rate limits, and result sizes. Limits are evaluated live on every request.'
related:
  - papers-api/authentication
  - dashboard
  - papers-api/examples
---

# Rate Limits & Quotas

All Papers API usage is governed by your active ScholarXIV subscription (Free, Plus, or Pro). Limits are checked live against your current plan on every request.

## Entitlements by Plan

| Plan  | Max Keys | Rate Limit (requests/hour) | Max Results per Request | Recommended For                  |
|-------|----------|----------------------------|-------------------------|----------------------------------|
| Free  | 2        | 1,200                      | 2,000                   | Testing and small personal tools |
| Plus  | 5        | 2,400                      | 4,000                   | Active development & moderate traffic |
| Pro   | 20       | 3,600                      | 6,000                   | Production apps and high volume  |

> [!TIP]
> Upgrade via the main [Pricing page](/pricing). Changes apply within seconds.

## How Limits Work

- **Live resolution**: On every API call, the server looks up your current active subscription and applies its entitlements. There is no caching of old limits.
- **Shared per user**: The hourly rate limit is across **all** your API keys. Multiple services or teammates on the same account compete for the same quota.
- **Rolling window**: The 60-minute window rolls continuously. When you hit the limit you receive a `429` with a `Retry-After` header.
- **Max results**: `limit` / `maxResults` is capped per plan — Free (2,000), Plus (4,000), Pro (6,000).

**Key fact**: A key created while on Pro will automatically run under Free limits if you later downgrade or cancel.

## Plan Changes & Quota Behavior

**Upgrades** are immediate. Your next request uses the new higher limits.

**Downgrades and cancellations**:
- Rate limit and max results drop on the next call.
- The system automatically disables the oldest enabled keys until you are back within the new plan's `maxKeys`.
- Disabled keys remain in your dashboard but will return 401 until re-enabled (after upgrading).
- You can manually manage which keys stay active within the new lower quota.

**Example scenario**

You are on Pro (20 keys allowed, 3,600 req/h) with 15 active keys. You downgrade to Free (2 keys, 1,200 req/h):

- All future requests are limited to 1,200 per rolling hour.
- The 13 oldest keys are automatically disabled.
- The 2 newest keys remain enabled.
- The disabled keys stay visible in the dashboard. You can re-enable them later if you upgrade.

This same enforcement runs on key creation and enabling a key.

**Best practice**: When planning a downgrade, decide in advance which services are critical and keep only those keys active. Treat keys as inexpensive and easy to rotate.

## Monitoring & 429s

- Watch the **Usage** page in the Developer Dashboard for real-time consumption and per-key breakdown.
- On rate limit: respect the `Retry-After` header and implement backoff in your client.
- The dashboard request logs show both successful calls and auth failures (with key prefix for the latter).

See the [Examples](/developers/docs/papers-api/examples) page for ready-to-use retry and backoff code.

## Related

- [Authentication](/developers/docs/papers-api/authentication) — how keys are validated against your live subscription.
- [Dashboard Usage](/developers/docs/dashboard/usage) — charts and request history.
- [Errors](/developers/docs/papers-api/errors) — full error reference including 429 handling.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).