Skip to main content
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

1

Open the dashboard

In Consensus, click your profile icon and choose API & MCP Dashboard.
2

Create a key

Open Keys and clients, click New key, and name it. The full key is shown once.
3

Send it on every request

Pass the key in the x-api-key header. Requests without a valid key return 401.

​
What each plan includes

* Returned on the first 50 search results and on Thread citations when you’ve selected your institution in Consensus settings. An organization key uses the institution of the person who created it. Every plan can use every search filter. Compare plans at 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.
  • A Thread is charged by the amount of work the agent does. mode controls the effort: a deep run does more work than a pro run, so it costs more. A failed run costs nothing. While a Thread runs, its maximum possible cost counts as used. If that doesn’t fit under your plan’s limit, creating the Thread or adding a follow-up returns 429.
  • 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. The Threads endpoints follow the same one-request-per-second limit, except GET /v1/threads/{thread_id}, which allows up to three requests per second. While a Thread is running, poll it about every 30 seconds.

​
Errors

​
Enterprise

Enterprise adds custom call volumes and rate limits and up to 1,000 papers per request. Enterprise keys authenticate the same way as every other key: send them in the x-api-key header on requests to api.consensus.app.
Authorization: Bearer is for the MCP server (mcp.consensus.app/mcp), not the REST API. See MCP API key access.
For Enterprise access, contact sales. Setting Consensus up behind an AI gateway or in Microsoft 365 Copilot? See the Enterprise guides.

Get started

Your first request, and a real response with full-text excerpts.

MCP plans and access

The same plans on the MCP server, with its per-plan result and field limits.