GET /v1/search returns ranked papers for a query in a single request. Use it when your code or your own model needs the papers themselves: titles, journals, citation counts, links, and full-text excerpts.
When to use search
Search is the right fit when you want the papers and plan to do the reasoning yourself.- Lookups: find the papers on a specific question, author, or method.
- Your own pipeline: feed ranked papers and full-text excerpts into your own LLM, agent, or scoring step.
- High volume: screen many queries or targets quickly. Each request costs one call per 100 papers returned.
- Structured filtering: narrow by study design, date, journal quality, sample size, field, or country.
Make a request
Store your key in an environment variable namedCONSENSUS_API_KEY, then send a query:
results carries the paper’s title, authors, journal_name, publish_year, citation_count, doi, a Consensus url, and a one-sentence takeaway, plus its paper_id and full_text_available. On a paid plan, open-access results also carry full_text_chunks: the passages from the paper’s full text that answer your query.
Go further
- Full-text excerpts: returned on paid plans for open-access papers. See Full text in the API.
- Complete text: pass the
paper_idof results wherefull_text_availableistruetoGET /v1/papers/full_textto read the whole paper as Markdown. Paid plans. See complete text. - Institutional full-text links: on a paid plan, if you’ve selected your institution in Consensus settings, the first 50 results can include an
institutional_access_urlthat opens the full text through your library. - More results: raise
page_sizeand page through withpage. Your plan sets the maximum. See plans and access. - Every parameter: see the search endpoint reference.
Use cases
Abstract screening
Screen candidate papers against inclusion criteria at scale.
Citation verification
Check that a claim is backed by the paper it cites.
Extract values from full text
Pull doses, effect sizes, and sample sizes from full-text excerpts.
Scheduled research pipeline
Monitor a field on a schedule and report what’s new.