---
title: "FAQ"
description: "Common questions about authentication, search, rate limits, plan changes, pagination, and production best practices for the Papers API."
canonical_url: "https://www.scholarxiv.com/developers/docs/papers-api/faq"
markdown_url: "https://www.scholarxiv.com/developers/docs/papers-api/faq.md"
---

# FAQ
URL: /developers/docs/papers-api/faq
LLM index: /llms.txt
Description: Common questions about authentication, search, rate limits, plan changes, pagination, and production best practices for the Papers API.

# FAQ

## What is the Papers API and what can I do with it?

The Papers API lets you search the ScholarXIV paper index programmatically. It is a read-only search API that returns structured metadata — titles, authors, abstracts, categories, dates, and PDF links.

You can use it to build research tools, power academic search features in your own applications, feed paper data into AI agents, or automate literature review workflows. It does **not** manage collections, likes, bookmarks, or any user-specific state — it is purely a paper search and retrieval API.

See the [Papers API Overview](/developers/docs/papers-api) for endpoints and response format.

## Do I need a paid subscription to use the API?

No. The Free plan gives you 2 API keys and 100 requests per hour — enough for testing and small personal tools. If you need higher throughput, more keys, or production-level reliability, upgrade to Plus (300 req/h, 5 keys) or Pro (2,000 req/h, 20 keys).

Limits are evaluated live from your current subscription on every request. See [Rate Limits & Quotas](/developers/docs/papers-api/limits) for the full entitlements table.

> [!TIP]
> You can test the API with the Free plan and upgrade at any time — changes apply within seconds.

## How do I get an API key?

1. Log in to ScholarXIV.
2. Go to the [Developer Dashboard](/developers/dashboard/apikeys).
3. Click **Create API Key**, name it, and optionally set an expiration.
4. Copy the key immediately — it starts with `sxv_` and is shown **only once**.

Send the key in every request using either header:

```http
Authorization: Bearer sxv_your_key_here
```

```http
x-api-key: sxv_your_key_here
```

> [!WARNING]
> Store the key in an environment variable immediately. Never embed it in client-side code, public repos, or logs.

See [Authentication](/developers/docs/papers-api/authentication) for the full key management guide and security checklist.

## What is the difference between GET and POST search?

**GET** (`/api/v1/papers/search?q=...`) is a simple title-only search — fast and minimal. Use it for autocomplete, quick lookups, or single-input search bars.

**POST** (`/api/v1/papers/search`) is advanced search. You send a JSON body with any combination of filters — title, author, abstract, category, arXiv ID, and more. Filters are ANDed together, giving you precise control over results.

```json title="POST body example"
{
  "searchFilterString": {
    "all": "retrieval augmented generation",
    "cat": "cs.CL"
  },
  "limit": 20,
  "sortBy": "submittedDate",
  "sortOrder": "descending"
}
```

See [Search](/developers/docs/papers-api/search) for the full filter reference and recipes.

## How does pagination work? How do I get all results?

Pagination is zero-based (`page=0` is the first page). Every response includes a `pagination` object:

```json
{
  "page": 0,
  "limit": 20,
  "hasMore": true,
  "nextPage": 1
}
```

Always drive your loop from `nextPage` — never hard-code page numbers. When `nextPage` is `null` or `hasMore` is `false`, you have reached the end.

```ts title="Pagination loop"
let page = 0;
const allPapers = [];

while (page !== null) {
  const { data } = await client.post('/api/v1/papers/search', {
    searchFilterString: { all: 'large language models' },
    page,
    limit: 100
  });
  allPapers.push(...data.data);
  page = data.pagination.nextPage;
}
```

> [!IMPORTANT]
> Guessing page numbers or assuming sequential pages will miss or duplicate results. Always use the `nextPage` value the API returns.

See [Code Examples](/developers/docs/papers-api/examples) for complete pagination code.

## What happens when I hit the rate limit?

You receive a `429` response with a `Retry-After` header indicating how many seconds to wait. The rate limit is a rolling 60-minute window shared across **all** your API keys.

Implement backoff in your client:

```ts
if (res.status === 429) {
  const retryAfter = Number(res.headers.get('retry-after')) || 60;
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  // retry the request
}
```

If you consistently hit the limit, check your usage on the [Usage dashboard](/developers/docs/dashboard/usage) and consider upgrading your plan for higher throughput.

See [Rate Limits & Quotas](/developers/docs/papers-api/limits) for plan-specific limits and the [Code Examples](/developers/docs/papers-api/examples) page for a complete retry helper.

## What happens to my API keys if I downgrade or cancel my plan?

When you downgrade — for example from Pro (20 keys) to Free (2 keys) — the system **automatically disables the oldest enabled keys** until you are within the new plan's key limit. The 2 newest keys remain active.

Disabled keys stay visible in your dashboard but return `401` on any request. You can re-enable them later if you upgrade again. Rate limits and max results also drop to the new plan's values on your next API call.

> [!TIP]
> Before downgrading, decide which services are critical and plan which keys to keep. Keys are inexpensive and easy to rotate.

See [Rate Limits & Quotas](/developers/docs/papers-api/limits#plan-changes--quota-behavior) for the full scenario walkthrough.

## What do the common error codes mean and how do I fix them?

| Status | Message | Likely Cause |
|--------|---------|-------------|
| 400 | `Missing search query` | GET request without `q` parameter |
| 400 | `Missing advanced search filters` | POST with empty `searchFilterString` |
| 401 | `API Key is required` | Missing `Authorization` or `x-api-key` header |
| 401 | `Invalid API key format. Should start with 'sxv_'` | Wrong key format |
| 401 | `Invalid API key` | Key was revoked, expired, or does not exist |
| 429 | `Rate limit exceeded` | Hit your plan's hourly limit — respect `Retry-After` |

**Quick troubleshooting checklist:**
1. Key starts with `sxv_` and is in the correct header with the `Bearer ` prefix.
2. For POST: `searchFilterString` has at least one non-empty value.
3. `limit` is between 1 and 100.
4. On 429: check your dashboard and back off.
5. Pagination: always use `nextPage` from the previous response.

See the [Errors](/developers/docs/papers-api/errors) page for the full reference and defensive client patterns.

## Can I search by arXiv ID or specific authors?

Yes. Use the advanced search (POST) with the `id` or `au` filter:

**Search by arXiv ID:**
```json
{ "searchFilterString": { "id": "2401.01234" }, "limit": 1 }
```

**Search by authors (comma-separated):**
```json
{ "searchFilterString": { "au": "Vaswani, Shazeer" } }
```

The `id` filter matches arXiv ID, extracted ID, and base arXiv ID fields. The `au` filter accepts comma-separated author names for broader matches.

See the [Search](/developers/docs/papers-api/search) page for all available filters and more examples.

## What are the best practices for using the API in production?

1. **Store keys securely** — environment variables only, never in client code or repos.
2. **Separate keys per environment** — different keys for dev, staging, and production.
3. **Rotate keys regularly** — create a new key, deploy it, then delete the old one.
4. **Drive pagination from `nextPage`** — never hard-code page numbers.
5. **Handle 429s with backoff** — use the `Retry-After` header and exponential backoff.
6. **Use a server-side proxy** — a thin wrapper hides your key and lets you add caching, logging, and per-user quotas.
7. **Log safely** — never log full keys. Log only the prefix (e.g. `sxv_abc...`) which matches what the dashboard shows.
8. **Monitor usage** — check the [Usage dashboard](/developers/docs/dashboard/usage) before large jobs or agent runs.

> [!TIP]
> The [Code Examples](/developers/docs/papers-api/examples) page has ready-to-copy production patterns including a defensive client wrapper, retry logic, and safe logging.

Still stuck? Use the **Playground** in the Developer Dashboard to test requests and see exactly what the server receives.

## 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).