> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consensus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API plans and access

> What each Consensus plan includes on the API: monthly calls, papers per request, pagination, full-text excerpts, and rate limits.

The API is self-serve on every Consensus plan. Your plan sets how many calls you get each month, how many papers each request can return, and which features you can use.

## Get a key

<Steps>
  <Step title="Open the dashboard">
    In Consensus, click your profile icon and choose **API & MCP Dashboard**.
  </Step>

  <Step title="Create a key">
    Open **Keys and clients**, click **New key**, and name it. The full key is shown once.
  </Step>

  <Step title="Send it on every request">
    Pass the key in the `x-api-key` header. Requests without a valid key return `401`.
  </Step>
</Steps>

## What each plan includes

|                                      | Free             | Pro              | Teams            | Deep             | Enterprise |
| ------------------------------------ | ---------------- | ---------------- | ---------------- | ---------------- | ---------- |
| Included calls per month             | 30               | 500              | 500              | 2,000            | Custom     |
| Max calls with additional usage      | 30               | 1,000            | 1,000            | 10,000           | Custom     |
| Max papers per request (`page_size`) | 20               | 300              | 300              | 750              | 1,000      |
| Pagination past the first page       | No               | Yes              | Yes              | Yes              | Yes        |
| [Full-text excerpts](/api-full-text) | No               | Yes              | Yes              | Yes              | Yes        |
| Rate limit                           | 1 request/second | 1 request/second | 1 request/second | 1 request/second | Custom     |

Every plan can use every search filter. Compare plans at [consensus.app/pricing](https://consensus.app/pricing).

## How calls are counted

* **One call per 100 papers returned**, rounded up, with a minimum of one call per request. A request that returns 20 papers is 1 call; 150 papers is 2 calls.
* **API and MCP share one monthly pool.** Searches from your API key and from your MCP connection draw down the same allowance.
* **Usage resets on the 1st of each month.** Track it in the **Usage** tab of the API & MCP Dashboard.

### Additional usage

Pro, Teams, and Deep can keep making calls past the included amount, up to the plan's maximum, at **\$0.05 per call**. Additional usage is off by default; turn it on in the API & MCP Dashboard. Free plans stop at 30 calls.

## Page size and pagination

* **`page_size` defaults to 20.** A larger value is capped to your plan's maximum rather than rejected, so check the `page_size` echoed in the response.
* **Pages are zero-indexed.** Requesting `page=1` or later needs a paid plan; on Free it returns `403`.
* **A query returns at most 1,000 results in total.** `(page + 1) × page_size` can't exceed 1,000 on any plan. With `page_size=250`, pages 0–3 cover the full 1,000. To go wider, split the topic into narrower queries or tighter filters.

## Rate limits

Every self-serve plan allows **one request per second** per account. A faster request returns `429` with a `retry-after` header; wait that long and retry. Enterprise accounts can have custom limits.

## Errors

| Status                             | Meaning                                         | What to do                                             |
| ---------------------------------- | ----------------------------------------------- | ------------------------------------------------------ |
| `401`                              | Missing, invalid, or revoked key                | Check the `x-api-key` header, or create a new key      |
| `402`                              | Billing is past due                             | Resolve payment in your account; calls resume after    |
| `403` `feature_not_allowed`        | Pagination or full-text excerpts on a Free plan | Upgrade to a paid plan                                 |
| `429` "used all included searches" | Monthly calls used up                           | Turn on additional usage, upgrade, or wait for the 1st |
| `429` "Too many requests"          | More than one request per second                | Wait for `retry-after`, then retry                     |

## Enterprise

Enterprise adds custom call volumes and rate limits, up to 1,000 papers per request, and Bearer-token authentication:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

For Enterprise access, [contact sales](https://consensus.app/home/contact/sales/). Setting Consensus up behind an AI gateway or in Microsoft 365 Copilot? See the [Enterprise guides](/enterprise/overview).

## Related

<CardGroup cols={2}>
  <Card title="Get started" icon="rocket" href="/api-get-started">
    Your first request, and a real response with full-text excerpts.
  </Card>

  <Card title="MCP plans and access" icon="plug" href="/mcp-plans-and-access">
    The same plans on the MCP server, with its per-plan result and field limits.
  </Card>
</CardGroup>