---
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://www.scholarxiv.com/developers/docs/papers-api/limits"
markdown_url: "https://www.scholarxiv.com/developers/docs/papers-api/limits.md"
---

# Rate Limits & Quotas
URL: /developers/docs/papers-api/limits
LLM index: /llms.txt
Description: Your subscription controls API key quotas, hourly rate limits, and result sizes. Limits are evaluated live on every request.

# 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        | 100                        | 100                     | Testing and small personal tools |
| Plus  | 5        | 300                        | 100                     | Active development & moderate traffic |
| Pro   | 20       | 2,000                      | 100                     | 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 always capped at 100 per request (regardless of plan).

**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, 2000 req/h) with 15 active keys. You downgrade to Free (2 keys, 100 req/h):

- All future requests are limited to 100 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).