Skip to main content
New to the API? Make your first request with the quickstart, then come back here.
Abstracts leave out most of what you need: doses, methods, measured values, limitations. The Consensus API returns the text inside open-access papers in two ways: excerpts that come back with every search, and the complete text of the papers you pick. 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 in full_text_chunks:
A real response, trimmed to one result with shortened excerpts:
The 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

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.
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.
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.
Bronze papers (free to read on the publisher’s site, but without an open license), closed papers, and papers whose status is unknown never carry excerpts. Neither do retracted papers.
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.
When excerpts matter more than coverage, add 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, and include_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 doi and url alongside every passage so an answer built on it stays citable.
  • Say which evidence you used. When a result has no full_text_chunks and 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 url to 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.
The response has one result per paper you named, paper ids first and then DOIs, each in the order you sent them:
Illustrative and trimmed. Two open-access papers came back, so the request cost 2 credits. The blocked paper cost nothing.

What comes back

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.
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.
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’s status 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_until can 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 429 and nothing is charged. After the response, you pay only for the papers returned. credits_charged shows 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.
Complete text needs a paid plan: Pro, Deep, Teams, or Enterprise. On a Free plan the request returns 403 feature_not_allowed. See plans and access.

In MCP: search, then get_full_text

The MCP server offers the same complete text through the get_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.

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.