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

Sign in to Consensus and go to consensus.app/api-mcp, or click your profile icon and choose API & MCP Dashboard.
2

Create a key

Click Create API key, name it, and copy it. If you already have a key, open Keys and clients and click New key. 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. ** GET /v1/papers/full_text, at 1 credit per paper returned. *** GET /v1beta/papers/citations and GET /v1beta/papers/references, at 1 credit per 100 papers returned. Both are in beta, so their request and response schemas may change in the coming days. 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.
  • One credit per full text returned. Complete text costs 1 credit for each paper whose Markdown comes back, and a credit counts the same as a call. Papers that come back blocked or not found cost nothing. A paper charged to you in the last 24 hours, through the API or MCP, normally comes back free.
  • One credit per 100 citing or cited papers returned. GET /v1beta/papers/citations and GET /v1beta/papers/references are charged by the papers on the page, rounded up, with a minimum of 1 credit per request.
  • 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. That limit is shared across all of your account’s Threads. While a Thread is running, poll it every poll_after_seconds: 5 seconds for pro, 20 for deep. GET /v1/papers/full_text, GET /v1beta/papers/citations, and GET /v1beta/papers/references each allow one request per second on every plan, Enterprise included.

Errors

Enterprise

Enterprise adds custom call volumes and rate limits and up to 1,000 papers per request. An Enterprise contract covers search only: complete text, citations and references, and Threads are billed per credit at the standard rate, on top of the contract. 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.