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

> The Consensus API lets you integrate research search into your own applications, agents, and workflows. One REST endpoint, 220 million papers, self-serve keys.

The Consensus API puts Consensus search inside your own applications, tools, and workflows. Send a query, get back ranked peer-reviewed papers with metadata, and skip running each search by hand.

The API is self-serve and open to everyone.

```text theme={null}
GET https://api.consensus.app/v1/search
```

<Card title="Get started with the API" icon="rocket" href="/api-get-started">
  Authentication, your first request in cURL, Python, JavaScript, and Go, and the full parameter reference.
</Card>

## What you get

* The top 20 most relevant papers per query by default, up to 1,000 per query with `page_size`
* A relevance score on every paper for ranking or pruning
* Metadata: title, authors, journal, publication year, DOI, citation count, and a link to the paper
* Enriched fields on paid plans: study design, journal rank, extracted key takeaways, and query-relevant full-text excerpts (`include_full_text_chunks`)
* Filters for publication date, study type, sample size, citation count, journal quality, academic field, country, open-access status, and more

## Who it's for

* Automating research discovery for R\&D teams
* Powering private ChatGPT instances and internal copilots
* Giving internal AI agents trusted research references
* Building research dashboards and automation tools

## Get a key

<Steps>
  <Step title="Open the dashboard">
    Click your profile icon in the bottom-left of Consensus and choose **API & MCP Dashboard**.
  </Step>

  <Step title="Create a key">
    Open the **Keys and Clients** tab, click **New key**, and name it.
  </Step>

  <Step title="Copy it now">
    The full key is shown once. If you lose it, revoke it and create a new one.
  </Step>
</Steps>

<Frame caption="Profile icon › API & MCP Dashboard › Keys and clients › New key.">
  <img src="https://mintcdn.com/consensus-f7e6ffce/wHajK_wM4l0mxqJf/images/help/api-01.png?fit=max&auto=format&n=wHajK_wM4l0mxqJf&q=85&s=0ec1b542f110d2f70e18bd9595fc7c94" alt="The API & MCP Dashboard with the profile menu, Keys and clients tab, and New key button highlighted" width="1600" height="861" data-path="images/help/api-01.png" />
</Frame>

Send the key in the `x-api-key` header on every request. Treat it like a password: keep it out of client-side code, public repositories, and screenshots.

## Plans and limits

API and MCP calls share one monthly pool.

| Plan       | Included calls per month | Max with additional usage | Max papers per call |
| ---------- | ------------------------ | ------------------------- | ------------------- |
| Free       | 30                       | 30                        | 10                  |
| Pro        | 500                      | 1,000                     | 300                 |
| Teams      | 500                      | 1,000                     | 300                 |
| Enterprise | 500                      | 1,000                     | Custom              |
| Deep       | 2,000                    | 10,000                    | 750                 |

* A call covers up to 100 papers, rounded up, with a minimum of 1 call per request.
* Additional usage costs \$0.05 per call. It's off by default; enable it in the dashboard. Free plans can't enable it.
* Rate limit: 1 request per second.
* Usage resets on the 1st of each month.

<Frame caption="The Usage tab splits calls between API and MCP over 7 days, 30 days, or the billing period.">
  <img src="https://mintcdn.com/consensus-f7e6ffce/wHajK_wM4l0mxqJf/images/help/api-02.png?fit=max&auto=format&n=wHajK_wM4l0mxqJf&q=85&s=50bc7e8e2e3901482b4b88580bfc088d" alt="The API & MCP Dashboard's Usage tab with a bar chart of API and MCP calls" width="1437" height="970" data-path="images/help/api-02.png" />
</Frame>

## Common errors

| Status                             | Meaning                                                  |
| ---------------------------------- | -------------------------------------------------------- |
| `401`                              | Invalid or revoked key, or missing `x-api-key` header    |
| `402`                              | Billing past due — calls pause until payment is resolved |
| `429` "used all included searches" | Monthly pool exhausted; resets on the date shown         |
| `429` "Too many requests"          | More than 1 request per second                           |

<Note>
  Need higher limits or Bearer-token auth? Contact [sales@consensus.app](mailto:sales@consensus.app) about Enterprise access.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="API reference" icon="book" href="/api-reference/query-for-relevant-papers">
    Every parameter and response field.
  </Card>

  <Card title="MCP" icon="plug" href="/core-features/mcp">
    The same search inside Claude, ChatGPT, and Cursor.
  </Card>
</CardGroup>