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.
modecontrols the effort: adeeprun does more work than aprorun, 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 returns429. - 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/citationsandGET /v1beta/papers/referencesare 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_sizedefaults to 20. A larger value is capped to your plan’s maximum rather than rejected, so check thepage_sizeechoed in the response.- Pages are zero-indexed. Requesting
page=1or later needs a paid plan; on Free it returns403. - A query returns at most 1,000 results in total.
(page + 1) × page_sizecan’t exceed 1,000 on any plan. Withpage_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 returns429 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 thex-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.Related
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.