Search itself also reads full text, on every plan: queries are matched against titles, abstracts, and full text where Consensus holds it, so a paper can rank on what’s in its methods or results. See how search works.
Excerpts
Example
On a paid plan, open-access results carry excerpts infull_text_chunks:
takeaway gives you the paper’s conclusion. The excerpts give you the doses and study designs behind it, which the abstract doesn’t.
As of November 2026, you no longer need to send
include_full_text_chunks=true: paid plans return excerpts by default. Send include_full_text_chunks=false to leave them out when you only need metadata.What comes back
Format
Format
full_text_chunks is a list of strings. Each one starts with the section of the paper it came from, then the passage: Section: <heading> | <passage>. Split on the first | to separate them.How many excerpts
How many excerpts
Up to 3 excerpts per paper, for the first 20 eligible papers on each page, so at most 60 per request. Later papers on a larger page carry none. Excerpts are the passages most relevant to your query across those papers, so some may carry fewer than 3, or none. To get excerpts across more papers, keep
page_size at 20 and page through with page.When a paper has none
When a paper has none
A result has no
full_text_chunks field when the paper doesn’t meet the open-access rule, Consensus has no indexed text for it, no passage matched your query, or it comes after the first 20 eligible papers on the page. Fall back to abstract and takeaway for those papers. Excerpts never fail a search: if the excerpt lookup errors or takes too long, the results come back without them.Which papers have excerpts
Excerpts come only from open-access papers, whatever your plan. A paper qualifies when both of these hold:- Its open-access status is gold, diamond, green, or hybrid: the publisher’s version of the article, or a repository copy, is open.
- The text Consensus holds came from an open source: arXiv, CSHL (bioRxiv, medRxiv), OpenAlex, PubMed Central, or S2ORC. Text from a publisher feed never qualifies, whatever the paper’s open-access status.
Consensus also reads paywalled full text from its publisher partners. Search excerpts and complete text never return it, even when your organization has access to those publishers. Threads are the exception: when a Thread’s analysis cites a paywalled paper, that citation’s grounding quotes (
citations[].snippets) can come from the paper’s full text.open_access=true to limit results to open-access papers, so more of each page can carry them.
Excerpts by plan
Excerpts are available on all paid plans: Pro, Deep, Teams, and Enterprise. Retrieval over full text works on every plan. Free plan searches return no excerpts, andinclude_full_text_chunks=true on a Free plan returns 403 with the code feature_not_allowed.
The MCP server’s search tool returns excerpts on paid plans too, up to 3 per paper for the first 5 eligible papers, and 12,000 characters per search, so an assistant can quote the passage behind each claim.
Get the most out of excerpts
- Phrase the query as the thing you want to find. Excerpts are chosen against your query, so “what dose of creatine improves working memory” returns dosing passages where “creatine” returns general ones.
- Keep each excerpt with its paper. Store the
doiandurlalongside every passage so an answer built on it stays citable. - Say which evidence you used. When a result has no
full_text_chunksand you fall back to the abstract, tell the reader. - Read the paper for anything high-stakes. Excerpts are passages, not whole papers. Request its complete text when it’s open access, or follow
urlto the paper.
Complete text
When a passage isn’t enough, read the whole paper: every method detail, every results table, the full discussion. Search first, pick the papers you want, then request their complete text.1
Search
Every search result carries a
paper_id and full_text_available. full_text_available is true when the paper is open access. It doesn’t promise text: a paper that was retracted, or whose copy in Consensus isn’t its open-access copy, comes back blocked, and a paper Consensus holds no text for comes back no_full_text.2
Pick papers
Collect the
paper_id of each paper you want to read, up to 20 per request. You can also name papers by DOI, or pass the citations[].paper_id values from a Thread.3
Request the text
Call
GET /v1/papers/full_text with one paper_ids or dois parameter per paper. Each paper whose status is available comes back as Markdown, with a list of its sections.What comes back
Markdown and sections
Markdown and sections
markdown is the paper’s complete text, with a ## heading wherever a new section starts. sections lists each heading with its offset, the character position where its heading line starts in markdown, so you can slice out one section. total_chars is the length of markdown. All three come back on every available paper.DOIs
DOIs
Send DOIs with or without a
https://doi.org/ or doi: prefix. A DOI result echoes the DOI, lowercased and without its prefix, plus the paper_id it resolved to. You can mix paper_ids and dois in one request, up to 20 combined. Naming the same paper twice returns it twice and charges it once.Errors
Errors
422 when a request names no papers, more than 20, or a value that isn’t a paper id from search or Thread results. 403 feature_not_allowed on a Free plan. 429 when you send more than one request per second, or when your remaining monthly allowance can’t cover every paper in the request. 503 when complete text is busy or can’t look up or read papers right now; when it’s busy, the response carries Retry-After: 1. Retry a 503 after a short wait. Nothing is charged for a refused request.Which papers have complete text
Complete text follows the same open-access rule as excerpts: gold, diamond, green, and hybrid papers whose text came from an open source such as arXiv or PubMed Central, never from a publisher feed. Your plan and your organization’s publisher access don’t change which papers qualify. Each result’sstatus says what happened to it:
Check
full_text_available on search results before you request, so you skip papers that are certain to come back blocked.
Credits
Complete text costs 1 credit per paper returned. A credit counts the same as a call against your plan’s monthly allowance, which the API and MCP share.- Free: papers that come back blocked, not found, or
no_full_text. - Charged once a day: a paper charged to you in the last 24 hours, through the API or MCP, comes back again for free, so retrying after a response doesn’t charge twice. This is best effort: a reread before
free_reread_untilcan still be charged, for example when the first charge didn’t complete. A request for the same paper sent before the first one has finished is charged too, so wait for a response before you retry. - Hold first, settle after: before reading, the request reserves 1 credit for each paper that could be charged. If that doesn’t fit in your remaining allowance, the whole request returns
429and nothing is charged. After the response, you pay only for the papers returned.credits_chargedshows what the request is priced at; the usage it counts can be lower, since a request that crosses your included allowance is counted only up to it, and a charge that fails counts nothing.
403 feature_not_allowed. See plans and access.
In MCP: search, then get_full_text
The MCP server offers the same complete text through theget_full_text tool, for every MCP client. Each paper in a search result shows an id: line, marked full text available when the paper is open access and get_full_text is available to you. Your assistant passes up to 3 of those ids, or DOIs, to get_full_text and gets each paper back as Markdown, up to 40,000 characters at a time. A longer paper ends with a cursor that reads the next part, free within the 24-hour re-read window. It costs the same 1 credit per paper returned.
Related
Extract numbers from full-text papers
A worked example that pulls values and their conditions out of excerpts.
Full text access
Where Consensus’s full text comes from, and how the app uses it.
Full text endpoint reference
Every parameter and response field of
GET /v1/papers/full_text.Search endpoint reference
Every search parameter, including
paper_id and full_text_available on results.