# Get started with Consensus API
Source: https://docs.consensus.app/api-get-started
Search over 220 million peer-reviewed research papers with the Consensus REST API.
The Consensus API lets you search 220+ million peer-reviewed papers over a single REST endpoint. Send a query and get back ranked papers with titles, authors, journals, publication years, citation counts, and direct links.
**Base URL**
```
https://api.consensus.app
```
## Authentication
Every request must include your API key in the `x-api-key` header.
```http theme={null}
x-api-key: YOUR_API_KEY
```
Don't have a key yet? Request API access at [consensus.app/home/api](https://consensus.app/home/api).
## Make your first request
Pass a `query` — the only required parameter. Store your key in an environment variable named `CONSENSUS_API_KEY` first.
```bash cURL theme={null}
curl "https://api.consensus.app/v1/search?query=creatine%20and%20cognitive%20function" \
-H "x-api-key: $CONSENSUS_API_KEY"
```
```python Python theme={null}
import os
import requests
resp = requests.get(
"https://api.consensus.app/v1/search",
headers={"x-api-key": os.environ["CONSENSUS_API_KEY"]},
params={"query": "creatine and cognitive function"},
)
resp.raise_for_status()
for paper in resp.json()["results"]:
print(paper["title"], "—", paper["journal_name"], paper["publish_year"])
```
```javascript JavaScript theme={null}
const params = new URLSearchParams({ query: "creatine and cognitive function" });
const resp = await fetch(`https://api.consensus.app/v1/search?${params}`, {
headers: { "x-api-key": process.env.CONSENSUS_API_KEY },
});
const { results } = await resp.json();
for (const paper of results) {
console.log(paper.title, "—", paper.journal_name, paper.publish_year);
}
```
```go Go theme={null}
package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"os"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.consensus.app/v1/search", nil)
req.Header.Set("x-api-key", os.Getenv("CONSENSUS_API_KEY"))
req.URL.RawQuery = url.Values{"query": {"creatine and cognitive function"}}.Encode()
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var body struct {
Results []struct {
Title string `json:"title"`
JournalName string `json:"journal_name"`
PublishYear int `json:"publish_year"`
} `json:"results"`
}
json.NewDecoder(resp.Body).Decode(&body)
for _, paper := range body.Results {
fmt.Printf("%s — %s %d\n", paper.Title, paper.JournalName, paper.PublishYear)
}
}
```
```php PHP theme={null}
response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
// Parse response.body() with your preferred JSON library (Jackson, Gson, ...)
System.out.println(response.body());
}
}
```
## Next steps
Full parameter list, response schema, and interactive playground.
Client code, examples, and issues for the Consensus API.
Prefer a no-code path? Connect Consensus to Claude, ChatGPT, and other MCP clients.
Explore the Consensus research platform.
# Query for relevant papers.
Source: https://docs.consensus.app/api-reference/query-for-relevant-papers
/openapi.json get /v1/search
The supported endpoint for searching academic papers. Use this instead of the legacy `/v1/quick_search` endpoint, which is deprecated and will be removed on 2027-02-07.
# Query for relevant papers (legacy).
Source: https://docs.consensus.app/api-reference/query-for-relevant-papers-legacy
/openapi.json get /v1/quick_search
This endpoint is deprecated. Use `GET /v1/search` instead. It will be removed on 2027-02-07.
# Get started with Consensus MCP
Source: https://docs.consensus.app/consensus-mcp
The Consensus MCP server enables AI assistants like ChatGPT, Claude, Gemini Spark, and other MCP-compatible clients to search over 220 million peer-reviewed academic research papers directly from the conversation.
Consensus MCP lets AI assistants search 220+ million peer-reviewed research papers. Connect your preferred client below. You'll be searching in under 2 minutes
**Server URL**
```text theme={null}
https://mcp.consensus.app/mcp
```
Add Consensus from the Claude connectors directory.
Add Consensus from the ChatGPT app directory.
## Connect Your Client
**One-click:** open [Consensus in the Claude directory](https://claude.ai/directory/65247229-f0c7-49df-9044-fcbb8b3894c6) and click **Connect**. Or connect manually:
Open [claude.ai](https://claude.ai) or the Claude desktop app and go to **Settings**.
Select **Connectors**, then **Browse connectors**.
Search for **Consensus** and click **Connect**.
Approve the sign-in with your Consensus account, or continue without one at reduced limits.
Ask a research question in any chat. Consensus appears in the tools menu.
```bash theme={null}
claude mcp add --transport http consensus https://mcp.consensus.app/mcp
```
OAuth will open in your browser automatically on first use. You can also trigger it manually with the `/mcp` command inside Claude Code.
**One-click:** open [Consensus in the ChatGPT app directory](https://chatgpt.com/plugins/plugin_asdk_app_6943e6f4a928819195962de16fb9ffe4) and click **Connect**. Or connect manually:
Open [chatgpt.com](https://chatgpt.com) and sign in.
Open **Apps** from the sidebar, search for **Consensus**, and click **Connect**.
Sign in with your Consensus account when prompted.
Ask a research question, or call it by name: "Use Consensus to find RCTs on…"
Search results display in an interactive widget showing top papers with citations and direct links.
Consensus also works with ChatGPT Deep Research. See [Using Consensus with ChatGPT Deep Research](#using-consensus-with-chatgpt-deep-research) below.
```bash theme={null}
codex mcp add consensus --url https://mcp.consensus.app/mcp
codex mcp login consensus
```
Or add to `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.consensus]
url = "https://mcp.consensus.app/mcp"
```
**One-click:** [Install in Cursor](https://cursor.com/en/install-mcp?name=consensus\&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25zZW5zdXMuYXBwL21jcCJ9). Or add to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"consensus": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.consensus.app/mcp"]
}
}
}
```
Add to your MCP configuration:
```json theme={null}
{
"servers": {
"consensus": {
"url": "https://mcp.consensus.app/mcp"
}
}
}
```
Add to your MCP configuration:
```json theme={null}
{
"mcpServers": {
"consensus": {
"serverUrl": "https://mcp.consensus.app/mcp"
}
}
}
```
Add Consensus as a custom app for Gemini Spark:
Go to [gemini.google.com](https://gemini.google.com) and sign in with a personal Google Account, then click **Settings & help** → **Connected Apps**.
Under **Custom apps for Spark**, click **Add a custom app** and paste the server URL:
```text theme={null}
https://mcp.consensus.app/mcp
```
Click **Next** and follow the prompts to finish OAuth. If your client doesn't support Dynamic Client Registration, expand **Advanced features** and enter your credentials.
Ask Gemini Spark a research question and it can call Consensus tools.
Requires access to Gemini Spark, a personal Google Account, Keep Activity turned on, and is currently available in the US. Workspace and school accounts are not supported yet.
**One-click:** install [Consensus for Copilot](https://marketplace.microsoft.com/en-us/product/WA200011861) from the Microsoft Marketplace.
Go to [Consensus for Copilot on the Microsoft Marketplace](https://marketplace.microsoft.com/en-us/product/WA200011861) and click **Get it now**.
Open Microsoft 365 Copilot in Outlook, Teams, or the Office app where Consensus is available.
Type a research question like 'What does the research say about creatine and cognitive function?' and Copilot will call Consensus to find relevant papers.
A [Consensus account](https://consensus.app/sign-up) is required. It is free to create.
This allows you to add Consensus as a custom tool in Copilot studio so it can be used with agents or other automations you have have. This type of authentication will
Go to Copilot studio and find the 'tools' tab on the left hand side.
Click 'new tool' to add a custom tool
You can also use the API to do this. But to use the MCP, click 'model context protocol'.
**Server name**
Consensus
**Server Description**
Consensus is the go-to MCP for academic research. Search 220M+ peer-reviewed papers from PubMed, Semantic Scholar, and ArXiv — filter by study type (RCTs, meta-analyses, systematic reviews), journal quality, sample size, and more. Get structured results with citations, study takeaways, and direct links, or run pre-built workflows for literature reviews, grant research, and evidence synthesis.
**Server URL**
[https://mcp.consensus.app/mcp](https://mcp.consensus.app/mcp)
**Authentication**
OAuth 2.0
**Type**
Dynamic Discovery
Thats it! This custom tool can now be used and shared with other team members. Each team member will be able to connect to their own Consensus account when they use the tool.
A [Consensus account](https://consensus.app/sign-up) is required. It is free to create.
Any client that supports remote MCP servers (Streamable HTTP) works. Point it at `https://mcp.consensus.app/mcp`. If your client supports OAuth, authentication is handled automatically.
## Using Consensus with ChatGPT Deep Research
Consensus also works with ChatGPT Deep Research. When Deep Research uses the Consensus app, it can search Consensus for relevant papers and retrieve full paper details for cited results.
Connect the Consensus app in ChatGPT using the steps above.
Start a Deep Research request in ChatGPT.
Ask ChatGPT to use Consensus for peer-reviewed research, for example:
> Use Consensus to research the evidence on exercise for depression. Prioritize systematic reviews, meta-analyses, and randomized controlled trials.
Deep Research may run multiple Consensus searches, refine filters, retrieve paper details, and return a cited synthesis with direct links to papers on Consensus.
## Verify Your Connection
Try one of these in your connected client. Each link opens the question pre-filled:
| Ask | Try it |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "What does the research say about creatine and cognitive function?" | [Claude](https://claude.ai/new?q=What%20does%20the%20research%20say%20about%20creatine%20and%20cognitive%20function%3F) · [ChatGPT](https://chatgpt.com/?q=What%20does%20the%20research%20say%20about%20creatine%20and%20cognitive%20function%3F) |
| "Find meta-analyses on mindfulness for anxiety published since 2020" | [Claude](https://claude.ai/new?q=Find%20meta-analyses%20on%20mindfulness%20for%20anxiety%20published%20since%202020) · [ChatGPT](https://chatgpt.com/?q=Find%20meta-analyses%20on%20mindfulness%20for%20anxiety%20published%20since%202020) |
| "Are there RCTs on intermittent fasting with more than 500 participants?" | [Claude](https://claude.ai/new?q=Are%20there%20RCTs%20on%20intermittent%20fasting%20with%20more%20than%20500%20participants%3F) · [ChatGPT](https://chatgpt.com/?q=Are%20there%20RCTs%20on%20intermittent%20fasting%20with%20more%20than%20500%20participants%3F) |
| "What is the strongest evidence for and against remote work productivity?" | [Claude](https://claude.ai/new?q=What%20is%20the%20strongest%20evidence%20for%20and%20against%20remote%20work%20productivity%3F) · [ChatGPT](https://chatgpt.com/?q=What%20is%20the%20strongest%20evidence%20for%20and%20against%20remote%20work%20productivity%3F) |
You should see results citing specific papers with titles, journals, years, citation counts, and direct links.
## Plans and Access
Your results depend on your Consensus plan, not your AI subscription (Claude Pro, ChatGPT Plus, etc. have no effect on Consensus results).
No account is needed to get started. Connect directly and try it out.
| Plan | Max Page Size | Included Monthly Calls | Extra Features |
| ---------- | ------------- | ---------------------- | ------------------------- |
| No Account | 3 | Unlimited | None |
| Free | 10 | 30 | Full abstracts |
| Pro | 300 | 500 | Study type, key takeaways |
| Deep | 750 | 2,000 | Study type, key takeaways |
| Teams | 300 | 500 | Study type, key takeaways |
Max Page Size is the per-request ceiling. Requests that omit `page_size` still return the default of 20 papers.
Calls are billed per 100 papers returned, rounded up, with a minimum of 1 call per request. For example, a request that returns 150 papers consumes 2 calls.
Paid plans can make calls beyond the included monthly limit when the account has an active metered API subscription and additional usage is enabled. Additional usage is billed at \$0.05 per call. Free plans are capped at the included limit.
Create a free account at [consensus.app/sign-up](https://consensus.app/sign-up) or upgrade at [consensus.app/pricing](https://consensus.app/pricing).
## Enterprise and API Key Access
For enterprise access with unlimited rate limits, include your API key as a Bearer token:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Contact Consensus for enterprise API access at [consensus.app/home/api](https://consensus.app/home/api).
## Search Tool
The search tool searches Consensus for peer-reviewed research papers. ChatGPT Deep Research may call this tool multiple times with different queries and filters while building a research report.
### Parameters
| Parameter | Type | Required | Description |
| ------------------ | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | string | Yes | The research question or topic to search for. Use specific academic terminology for best results. |
| year\_min | integer | No | Exclude papers published before this year. |
| year\_max | integer | No | Exclude papers published after this year. |
| study\_types | string array | No | Filter by study design. Values: rct, meta-analysis, systematic review, literature review, case report, non-rct experimental, non-rct observational study, non-rct in vitro, animal. |
| sjr\_max | integer | No | Filter by journal quality (SCImago Journal Rank quartile). 1 is Q1 (highest), 2 is Q2, 3 is Q3, 4 is Q4. |
| sjr\_min | integer | No | Minimum journal ranking quartile. 1 is Q1 (highest), 4 is Q4. Excludes better (lower-number) quartiles; for example, set to 2 to keep Q2–Q4. |
| human | boolean | No | Set to true to include only studies involving human subjects. |
| controlled | boolean | No | Set to true to include only controlled studies. |
| sample\_size\_min | integer | No | Exclude studies with sample sizes smaller than this number. |
| citation\_min | integer | No | Exclude papers with fewer citations than this number. |
| medical\_mode | boolean | No | Set to true for clinical, medical, or evidence-based medicine questions. Prioritizes top medical journals and clinical guidelines. |
| exclude\_preprints | boolean | No | Set to true to exclude preprints and return peer-reviewed papers only. |
| open\_access | boolean | No | Set to true to include only open-access papers. |
| duration\_min | integer | No | Minimum study duration in days. Useful for longitudinal or long-term studies. |
| duration\_max | integer | No | Maximum study duration in days. |
| country | string | No | Comma-separated ISO 3166-1 alpha-2 country codes (for example `us`, `gb`) to limit to those countries of study. Unknown codes are ignored. |
### Response
Each search returns:
Array of paper objects with `title`, `authors`, `abstract`, `journal`, `year`, `citation_count`, and `url` (direct link to the paper on Consensus).
Total number of papers found.
The original search query.
Pro plans and above also include `study_type` and `takeaway` for each paper. Enterprise includes `doi`.
### Example Prompts
* "What does the research say about the effectiveness of remote work on productivity?"
* "Find RCTs and meta-analyses since 2020 on cognitive behavioral therapy for anxiety"
* "Search for high quality human studies on gut microbiome and mental health with at least 100 participants"
* "Recent research on large language model hallucination from top tier journals"
* "Use Consensus Deep Research to compare evidence for different treatments for insomnia"
## Troubleshooting
You added the server with `-- --transport http` instead of `--url`. Remove and re-add:
```bash theme={null}
codex mcp remove consensus
codex mcp add consensus --url https://mcp.consensus.app/mcp
codex mcp login consensus
```
Fully quit and restart Claude Code. Do not just use the reconnect option. Your credentials are saved and will work after restart.
Your OAuth token has expired. Re-authenticate:
* **Claude Code:** Type `/mcp`, select Consensus, choose Clear authentication, re-authenticate, then restart Claude Code
* **Codex:** Run `codex mcp logout consensus` then `codex mcp login consensus`
* **Cursor:** Disconnect and reconnect the server in Settings then Tools and MCP
* **Claude Desktop:** Disconnect and reconnect the connector in Settings then Connectors
* **ChatGPT:** Disconnect and reconnect the Consensus app from ChatGPT Apps
* Verify the URL includes `/mcp` at the end
* Remove and re-add the server using the commands above
* Restart your client completely
This is normal. Claude loads tool definitions on demand when many tools are present. Retry the query and it will work on the second attempt.
Confirm the Consensus app is connected in ChatGPT Apps, then ask Deep Research to use Consensus explicitly. For example:
> Use Consensus to find peer-reviewed papers on this question and cite the strongest evidence.
Deep Research decides when to call connected tools, so it may not call Consensus for questions that are not research-focused.
Try broadening your search query or removing filters. Use specific academic terminology rather than casual language.
Paid plans can continue making calls past the included monthly limit when the account has an active metered API subscription and additional usage is enabled; extra usage is billed at \$0.05 per call, with each call covering up to 100 papers. Free plans must wait for the next monthly reset or upgrade.
Rate limits are per user for authenticated MCP clients. A 429 that says you're sending requests too quickly is a per-minute rate limit; wait a few moments and add backoff between requests. A 429 that mentions monthly call credits is a usage limit, not a rate limit.
## Security
* **Endpoint:** Only connect to the official URL: `https://mcp.consensus.app/mcp`
* **API keys:** Store securely using environment variables. Never share keys in prompts or public conversations. Rotate if compromised.
* **Data handling:** Search queries are sent to the Consensus API over HTTPS/TLS. Results contain publicly available academic paper metadata. No personal data is stored from MCP requests.
## Supported Platforms
| Platform | Auth | Status |
| ------------------------ | ------------ | --------- |
| Claude Desktop | OAuth | Supported |
| ChatGPT | OAuth | Supported |
| ChatGPT Deep Research | OAuth | Supported |
| Claude Code | OAuth | Supported |
| Codex | OAuth | Supported |
| Cursor | OAuth | Supported |
| VS Code (GitHub Copilot) | Config | Supported |
| Windsurf | Config | Supported |
| Gemini Spark | OAuth | Supported |
| Other MCP Clients | Bearer token | Supported |
## Additional Resources
Explore the Consensus research platform.
Full reference for the Consensus search API.
Learn more about the Model Context Protocol.
View the source, report issues, and star the Consensus MCP server.
# Use cases
Source: https://docs.consensus.app/use-cases
Get inspired by what you can build on Consensus. Browse real customer workflows by persona, each with the full prompt and API call behind it.
Browse what researchers, life-science teams, consultants and advisors, and engineers actually build on Consensus. Every card links to the full prompt you can copy and run today.
No use cases match that persona yet. Pick All to see everything.
## Next steps
Five primitives every workflow above is built from, and what makes a good Consensus use case.
Run any prompt on this page from Claude, ChatGPT, Claude Code, or Codex in under two minutes.
Your first authenticated request to `GET /v1/search`, in seven languages.
Higher page sizes, unlimited usage, and full-text access for corpus-scale work.
# Screen abstracts against inclusion criteria
Source: https://docs.consensus.app/use-cases/abstract-screening
Apply explicit inclusion and exclusion criteria across thousands of abstracts, with a decision log a second reviewer can audit.
## What you get
One row per record: include, exclude, or flag for human review — each with the criterion that decided it and a supporting quote. The most labour-intensive step in evidence synthesis, turned into something a human checks rather than performs.
Consensus gives you the primitives for this — filters, pagination, abstracts, and study types. It is not a packaged screening product, so you are building the workflow yourself. Customers ask us for this regularly; treat the recipe below as the current best path.
## Who it's for
Anyone running a systematic or scoping review — graduate students, methodologists, evidence synthesis units. Traditionally two people screen every abstract independently, which is where the weeks go.
## The prompt
```text theme={null}
You are a systematic review screener. Apply the criteria below to each record.
Do not summarize the papers. Do not decide what would be interesting.
Inclusion criteria:
[ONE PER LINE]
Exclusion criteria:
[ONE PER LINE]
For each record, work through the criteria in order and stop at the first one
that decides the case. Then output exactly one verdict:
- INCLUDE — meets every inclusion criterion, triggers no exclusion.
- EXCLUDE — fails a specific criterion. Name which one.
- FLAG — the abstract does not contain enough information to decide. Say which
criterion you could not evaluate and what you would need to read.
Rules:
- FLAG is not a failure state. A record whose abstract omits the sample size
cannot be excluded for sample size — flag it.
- Never infer a study design the abstract does not state. If it does not say
randomized, it is not an RCT for screening purposes.
- Quote the phrase that decided the verdict. A verdict with no quote is not
auditable and will not survive a second reviewer.
- Judge the record in front of you. Do not use anything you know about the
paper from elsewhere.
Output: Record ID | DOI | Verdict | Deciding criterion | Supporting quote |
Confidence (high/low).
```
## Calibrate before you scale
Screen a random sample by hand, then run the agent over the same 100 and compare. You are measuring agreement, and more importantly reading the disagreements.
Almost every disagreement traces to a criterion two humans would also read differently. Rewrite the criterion until it is unambiguous, then re-run.
A near-zero flag rate means the agent is deciding cases it cannot actually decide from an abstract. Somewhere between 5% and 20% is normal depending on how much your criteria depend on methods detail.
For flagged records, re-request with `include_full_text_chunks=true` using the criterion as the query, and screen the excerpts instead.
## Narrowing before you screen
Every filter you apply is a record you do not have to screen — but each one also risks dropping an eligible study, so record what each rung costs you.
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=resistance training older adults muscle strength" \
--data-urlencode "study_types=rct" \
--data-urlencode "human=true" \
--data-urlencode "sample_size_min=30" \
--data-urlencode "page_size=200"
```
Use the [filter ladder](/use-cases/best-practices#filter-ladder) and keep the count at each rung, because a reviewer will ask.
## Audit requirements
Follow the [grounding rules](/use-cases/best-practices#grounding-and-auditability). Screening specifically needs: total records retrieved, records after deduplication, screened, included, excluded by criterion, and flagged. Excluded counts must be reported per criterion — PRISMA requires reasons, not a single total.
## What to check before you trust it
* **Never let the agent be the only screener on a published review.** It is a first pass that a human adjudicates, and journals will ask who screened.
* **Check the excluded pile, not just the included one.** False exclusions are invisible in the output and fatal to the review.
* **Re-screen after any criterion change.** A mid-run rubric edit makes the earlier verdicts incomparable.
## Related
The step before screening: assembling the records.
Turn the log into the paragraph reviewers require.
Filter ladder, grounding rules, and the five primitives.
Browse the gallery by persona.
# Add a citable evidence layer to an agent you already ship
Source: https://docs.consensus.app/use-cases/add-an-evidence-layer
Give a working agent access to peer-reviewed literature as a tool, so its claims carry citations instead of assertions.
## What you get
An agent that already does something valuable, now grounded: every claim it makes traces to a real paper, and "the literature does not answer this" becomes an answer it can give.
The integration is a tool registration, not a re-architecture. Owkin shipped theirs to users in days.
## Who it's for
Product engineers whose agent works but overclaims — it reasons well and cites nothing, and your users have started noticing.
## How it went at Owkin
[Owkin](https://consensus.app/home/community-voices/owkin/) exposed Consensus to K Pro's orchestrator the same way it exposes its other tools. That architectural fit is the whole story: no new retrieval service, no corpus to maintain, no bespoke ranking layer.
> "The Consensus MCP slotted directly into our agentic stack and gave K Pro's capabilities a dramatic upgrade overnight."
>
> — **Lucas Brechot**, Senior Product Manager, AI Products, Owkin
Agents now ground their reasoning in full-text literature with programmatic controls for recency, citation count, and journal reputation — the filters a human researcher applies instinctively when judging whether a paper is relevant and credible.
## Wiring it in
```bash MCP theme={null}
# OAuth per user, so each person's own plan and limits apply
https://mcp.consensus.app/mcp
```
```bash REST theme={null}
# one service key, full control over pagination
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=your agent's search string"
```
Choose by auth model rather than by preference: **MCP** when each user should search under their own account and limits, **REST** when the integration needs one shared quota and programmatic pagination.
## What separates a grounded agent from a decorated one
One search per user question is the most common cause of thin answers. Split the question into subquestions and give each its own search with its own filters.
Request `include_full_text_chunks=true` so the generation step reasons over results paragraphs rather than the introduction.
Require a `doi` or `url` on every claim and drop unsupported sentences. Make "the literature does not answer this" a first-class output rather than a failure state.
Show the study types, years, and quality thresholds used. A researcher cannot trust a result set whose inclusion criteria are hidden.
Cache on every parameter, not the query string alone, with a short TTL so new literature still lands.
## What to check before you trust it
* **Check the unanswerable case.** Ask your agent something the literature genuinely does not settle. If it produces a confident cited answer anyway, your grounding rule is decorative.
* **Spot-check citations against claims.** A real paper attached to a claim it never made is the failure that survives review.
* **Watch your rate limit under real traffic.** Per-user OAuth spreads load across accounts; a shared service key concentrates it. See [rate limits](/use-cases/best-practices#rate-limits-and-result-caps).
* **Do not hide the filters.** If your product narrows to Q1 journals by default, say so in the UI.
## Related
When you already have a corpus and want it gone.
The retrieval pattern that makes a grounded agent good rather than merely cited.
Rate limits, grounding rules, and the five primitives.
Browse the gallery by persona.
# Benchmark literature providers against your own ground truth
Source: https://docs.consensus.app/use-cases/benchmark-retrieval
Build a curated query set with known-relevant papers and measure which retrieval provider actually surfaces them.
## What you get
A defensible answer to "which literature API should we build on", measured on your own domain rather than on a vendor's marketing page — and a regression harness you keep afterwards.
## Who it's for
The engineer choosing a retrieval provider, and whoever has to justify that choice to a technical buyer or a research team who will notice if it is wrong.
## How Phylo did it
Before putting anything into production, [Phylo](https://consensus.app/home/community-voices/phylo/) ran a head-to-head benchmark. The team curated biomedical queries spanning several disease areas, each with a ground-truth list of papers already known to be highly relevant, then measured **at top 20 results** how many of the truly relevant papers each system actually surfaced.
> "We benchmarked across many different providers. We ended up choosing Consensus."
>
> — **Kexin Huang**, Co-founder & CEO, Phylo
Questions should span the disease areas, research contexts, or subfields your product actually serves — including the awkward ones. A benchmark built only from easy queries measures nothing.
For each query, list the papers a domain expert would insist appear. This is the expensive part and the part that makes the result trustworthy; do not shortcut it with model-generated relevance labels.
How many ground-truth papers appear in the top k. Phylo used top 20. Fix k before you run anything, because choosing it afterwards is how benchmarks get massaged.
Different query phrasings favour different engines. Same strings, same k, and note where a provider needs different phrasing to perform — that is a real integration cost.
## Running it against Consensus
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=" \
--data-urlencode "page_size=20" \
--data-urlencode "include_semantic_score=true"
```
`include_semantic_score=true` returns a relevance score for the top 50 results, which lets you check score calibration alongside raw recall. It is API-only — the MCP `search` tool does not expose it.
Benchmark unfiltered first. Filters change recall substantially, and a comparison where one provider is filtered and another is not measures your configuration rather than the engines. Add filters in a second pass to see how much precision they buy.
## Keep it as a regression harness
The benchmark is more valuable after the decision than during it. Re-run it when you change prompts, filters, or query construction — it is the only way to tell whether a retrieval change actually helped or just felt better.
Split the score in two: **retrieval quality** (did the right papers come back) and **grounding faithfulness** (did the answer stay true to them). A pipeline can fail at either, and the fixes are unrelated.
## What to check before you trust it
* **Beware ground truth built from one provider's output.** If your labels came from a search on system A, system A wins by construction. Build them from expert knowledge or published reviews.
* **Report recall per query, not just the mean.** One catastrophic query hidden inside a good average is exactly the failure your users will hit.
* **Re-check page size.** Comparing top-20 against a provider capped below 20 is not a fair test — confirm the `page_size` echoed back matches what you asked for.
* **Say when the difference is noise.** With 30 queries, small gaps are not signal.
## Related
What to do once the benchmark decides it.
The workload that makes retrieval quality worth measuring.
Rate limits, grounding rules, and the five primitives.
Browse the gallery by persona.
# Best practices
Source: https://docs.consensus.app/use-cases/best-practices
The five primitives every Consensus workflow is built from, and how to tell a good use case from a poor one before you build it.
Every use case in the [gallery](/use-cases) is a combination of five primitives. If you build only one thing, build these — then compose them.
## The five patterns
| Pattern | What it does | How |
| ---------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Fan-out and merge** | Turns one question into 5–30 searches and one clean corpus | Issue queries one per second, deduplicate on `doi`, keep which query found what |
| **Filter ladder** | Trades recall for precision in controlled steps | Start unfiltered, then add `study_types`, then `human` and `controlled`, then `sjr_max` — record counts at each rung |
| **Exhaustive sweep** | Gets every record, not the first page | Walk `page` from `0` while `is_end` is false, following `next_page`, at your plan's max `page_size` |
| **Excerpt-first extraction** | Extracts numbers you can defend | Set `include_full_text_chunks=true` and phrase `query` as the thing being extracted, then keep each value with its excerpt |
| **Diff against last run** | Turns any search into a monitor | Window with `year_min` and `month_min`, diff on `doi` against stored state, report only the delta |
The filter ladder is the highest-leverage habit. Most disappointing Consensus results are an unfiltered query, and most empty ones are four filters applied at once. Move one rung at a time and keep the counts.
## Fan-out and merge
The single biggest quality difference between a thin answer and a good one. One query is one search; a real question deserves 5–30.
Split the question into subquestions — mechanism, population, outcome, competing explanations. Generate several phrasings per subquestion covering synonyms and adjacent terminology.
Every query is independent, but there is a one-query-per-second rate limit on every plan except Enterprise. Unbounded parallelism gets you 429s, not speed — run searches sequentially and build the pacing into your system. See [rate limits](#rate-limits-and-result-caps) below.
Merge on `doi`, keeping the first-seen record plus the list of queries that found it. How many queries surfaced a paper is a useful relevance signal in itself.
You will need both to describe your coverage, and a sharp drop tells you your phrasings were near-duplicates.
## Filter ladder
```bash theme={null}
# rung 0 — gauge volume
curl -G "https://api.consensus.app/v1/search" -H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=resistance training older adults muscle strength"
# rung 1 — design
--data-urlencode "study_types=rct,meta-analysis"
# rung 2 — population
--data-urlencode "human=true" --data-urlencode "sample_size_min=50"
# rung 3 — quality
--data-urlencode "sjr_max=1" --data-urlencode "exclude_preprints=true"
```
Record the result count at each rung. When a rung drops you to near-zero, that is the constraint to relax — and knowing which one it was is most of the diagnosis.
## Exhaustive sweep
```python theme={null}
def sweep(query, **filters):
page, out = 0, []
while page <= 49: # page is 0-indexed, 49 is the ceiling
body = search(query=query, page=page, **filters)
out.extend(body["results"])
if body["is_end"] or body.get("next_page") is None:
break
page = body["next_page"]
return out
```
Pagination and page sizes above the default of 20 require a paid plan or an Enterprise API key. `page_size` caps at 300 on Pro and Teams, 750 on Deep, and higher on Enterprise keys. A request over your ceiling is clamped rather than rejected — check the `page_size` echoed back in the response.
## Rate limits and result caps
Two separate ceilings shape every workflow here, and confusing them is the most common cause of a pipeline that quietly under-reports.
**Rate limit — how fast you may ask.** One search per second on every plan except Enterprise:
| Plan | Search queries per second | Results shown per search |
| ---------- | ------------------------- | ------------------------ |
| No account | Shared across all users | 3 |
| Free | 1 per user | 10 |
| Pro | 1 per user | up to 300 |
| Deep | 1 per user | up to 750 |
| Teams | 1 per user | up to 300 |
| Enterprise | Custom | 1,000+ |
Do not fan out with unbounded parallelism. Run searches one at a time and pace them, on every plan. Without an account the limit is shared across all users, so it is the least predictable option — sign in before building anything real.
Retrieving details for a paper you have already found is not the bottleneck — searching is.
**Result cap — how much comes back.** A response that says it found more papers than it returned has been capped by your plan. That distinction matters: **you can only cite what was shown**, and a thin result set may reflect your plan ceiling rather than a genuine gap in the literature. Parse both numbers, and when they differ, say so in your output rather than reporting the shown count as the whole literature.
**Handling 429s.** The two kinds mean different things:
* **Per-second rate limit** — there is a one-question-per-second limit on every plan except Enterprise. Account for it in whatever you are building rather than firing many searches in parallel: pace your calls, honour `retry-after`, and add jitter. Retrying helps.
* **Monthly search allowance** — you have used the searches included in your plan. Retrying does not help. Turn on additional usage in your account settings to keep searching past the included allowance.
A workable retry policy, and the one the Consensus-built skills use: on failure wait 3 seconds and retry once; after 3 consecutive failures across any combination of calls, stop and surface the problem rather than silently producing a thin result.
## Grounding and auditability
Every workflow in the gallery ends in something a person will act on — a citation in a manuscript, a target decision, a claim that ships. These five rules are what keep that output trustworthy, and they are the ones the Consensus-built skills enforce most strictly.
Never supplement results with model knowledge, a previous conversation, or a paper you happen to know. A fabricated citation in an academic or regulatory context costs far more than a thin result set. If you include something not retrieved in this session for context, label it explicitly and exclude it from every count.
**Queries sent**, **results returned**, and **results cited**. These are different numbers and conflating them is how a five-paper review gets described as comprehensive. Track all three from the first search, not retroactively.
When a response reports finding more papers than it returned, your plan capped it. Only the returned papers are citable. Surface it: a sparse section may reflect your ceiling rather than a genuine gap in the literature, and the reader cannot tell the difference unless you say which it was.
A step is not done because you sent the request — it is done when the response is back and contains data. On failure, wait 3 seconds and retry once; after 3 consecutive failures across any combination of calls, stop and report. Never silently skip a failed search, and never present partial coverage as complete.
No URL or DOI from this session means not citable. Enforce this at write time rather than at review time — it is the single check that catches the most problems.
### The audit log
End any workflow that produces a deliverable with a table of what it actually did:
| Search | Query | Filters used | Found | Returned | Cited | Status |
| ------ | ----------------------------------- | -------------------------------- | ----- | -------- | ----- | ---------------------------- |
| 1 | creatine muscle hypertrophy | `human`, `year_min: 2015` | 20 | 10 | 4 | Success |
| 2 | systematic review creatine strength | `study_types: systematic review` | 8 | 8 | 3 | Success |
| 3 | creatine cognitive function | `human` | 0 | 0 | 0 | Success, no results |
| 4 | creatine dosage timing | none | 11 | 11 | 2 | Failed once, retry succeeded |
Follow it with the totals, any plan cap you detected, and any search that failed after its retry. This is what lets a reader — or a reviewer, or a mentor — judge how much weight the output deserves, and it is cheap to produce if you have been counting from the start.
A run that found nothing is a result worth recording. An empty audit log entry distinguishes "no new evidence this week" from "the job broke silently three weeks ago."
## What makes a good Consensus use case
Consensus searches peer-reviewed literature. It answers "what does the published evidence say about X" extremely well. It is not a source for your internal experiment data, patent full text, regulatory filings, or private clinical data — join those to Consensus results rather than expecting Consensus to hold them.
The filters are where accuracy comes from. A question you can express as "human RCTs, 100+ participants, Q1 journals, since 2020" comes back far cleaner than an unfiltered keyword search. If you cannot describe the study population you want, spend a turn deciding it before you search.
Every result carries `title`, `authors`, `journal_name`, `publish_year`, `citation_count`, `doi`, and a `url` back to the paper on Consensus. Good use cases end in something a human can audit line by line — an evidence table, a cited memo, a screening decision log. Ones that end in an uncited assertion waste the citation trail.
Nearly every high-value workflow in the gallery is a fan-out. If your design issues one search and stops, you are leaving most of the quality on the table. Breadth comes from the number of queries, not from how fast you fire them — pace them to your tier's limit.
If the answer is one number from a database, a definition, or today's news, Consensus is the wrong tool. Reach for it when the answer is *contested*, *cumulative*, or *needs a citation*.
## Surface differences worth knowing
| | MCP | REST API |
| ------------------------ | ---------------------------------------------------------- | ----------------------------------------------- |
| Auth | OAuth per user, so each person's own plan and limits apply | One `x-api-key` for the whole integration |
| Best for | Interactive work and agent frameworks; no code to write | Pipelines, batch sweeps, and anything scheduled |
| `clinical_guideline` | Not exposed | Available |
| `include_semantic_score` | Not exposed | Available |
| Pagination control | Available on paid plans | Available on paid plans and Enterprise keys |
Browse all 12 use cases by persona.
Every filter, the full response schema, and an interactive playground.
# Create a biomarker evidence report
Source: https://docs.consensus.app/use-cases/biomarker-report
Assess the evidence for a biomarker's optimal range across Mendelian randomization, large cohorts, and trials — or establish that no evidence-based range exists.
## What you get
A tiered evidence report on one biomarker: what range the published evidence actually supports for the outcomes you care about, which evidence tiers support it, where the tiers disagree, and — when the evidence cannot bound a range — an explicit statement that it cannot, instead of a plausible-sounding number.
## Who it's for
Biotech and pharma teams, longevity clinicians, and translational researchers who need more than a lab reference interval. This is one of the heaviest real usage patterns on Consensus.
## The prompt
The structure below is what makes this work: the definitional constraints and the per-tier instructions do more for output quality than any amount of prompt polish. Replace `[BIOMARKER]` and the outcome set.
```text theme={null}
You are a clinical epidemiologist, longevity medicine researcher, and evidence
synthesis expert.
Task:
Assess all available evidence to determine the evidence-based optimal range of
the biomarker [BIOMARKER] in adults, optimized for longevity and disease-risk
reduction, not merely the conventional lab reference interval.
Population:
Adults, separated by sex where biologically or clinically relevant. Note
differences by age, menopausal status, pregnancy status, ethnicity, kidney
function, body composition, medication use, assay type, and disease state when
relevant.
Core question:
What biomarker range is most consistent with the lowest risk of all-cause
mortality, disease-specific mortality, major age-related disease, frailty, and
biological aging, where both the lower and upper bounds of the range are
supported by evidence that values outside the range are less favorable?
If such a true optimal range cannot be established, report the best-supported
risk thresholds and explicitly state that no evidence-based optimal range is
known.
Critical definition of "optimal range":
Do not define the optimal range as merely:
- within the standard reference interval;
- not clinically deficient;
- not clinically excessive;
- a range where higher or lower values have not been proven harmful;
- a range used as a treatment target in a clinical trial;
- a common clinical target;
- the middle of the reference interval.
Only call a range "optimal" if the evidence supports both its lower and upper
bounds. If proposing a bound that lies inside the conventional reference
interval, justify it with evidence that values beyond it are less favorable.
Explicitly report whether risk rises on both sides of the proposed range. If
only one side of the curve shows increased risk, do not claim a bounded optimal
range unless other evidence supports the opposite boundary.
Search each evidence tier separately using Consensus, and report them separately:
A. Randomized controlled trials
- Interventions that moved the biomarker and measured hard outcomes.
- Note whether the trial targeted a range or a threshold.
B. Systematic reviews and meta-analyses
- Pooled dose-response relationships where available.
C. Genetic and Mendelian randomization studies
- Assess whether genetically predicted differences in the biomarker are
associated with longevity, mortality, or disease outcomes.
- Discuss pleiotropy, instrument strength, directionality, and whether MR
supports causality.
- State which MR supports: lower is better, higher is better, mid-range
optimal, harm at high levels, harm at low levels, or no causal effect.
- Distinguish causal evidence for the biomarker itself from causal evidence
for related pathways or binding proteins.
D. Large observational cohorts
- Include dose-response, nonlinear, U-shaped, J-shaped, reverse J-shaped, or
threshold analyses.
- Extract nadir risk ranges where reported.
- Note adjustment covariates, reverse causation risk, and residual confounding.
- Report whether results differ after excluding early deaths, current smokers,
people with prevalent disease, and people with frailty, inflammation,
kidney disease, malnutrition, or major comorbidity.
- Do not interpret absence of additional benefit at high or low values as
evidence of harm.
Output:
1. Proposed optimal range with both bounds, or an explicit statement that none
can be established.
2. A table by evidence tier: what it shows, its direction, and its strength.
3. Where the tiers disagree, and the most likely reason.
4. Stratification notes where the answer differs by subgroup.
5. What evidence would most change this conclusion.
Cite every claim with journal, year, and DOI.
```
## How it works
Without the "do not define optimal range as…" list, models converge on the reference interval and call it an answer. Enumerating the wrong definitions is what forces a real evidence assessment.
Mendelian randomization and observational cohorts fail in different ways, so they need different critical questions. Searching them separately also makes tier disagreement visible instead of averaging it away.
This is the constraint that prevents a one-sided risk curve being reported as a bounded range — the most common error in biomarker summaries.
"No evidence-based optimal range is known" is frequently the correct answer. Naming it up front stops the model manufacturing a range to satisfy the request.
## The API equivalent
Run one call per tier and keep the results separate:
```bash theme={null}
# Tier C — Mendelian randomization
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=homocysteine Mendelian randomization all-cause mortality causal" \
--data-urlencode "human=true" \
--data-urlencode "domain=med,bio" \
--data-urlencode "page_size=50"
# Tier D — large cohorts, nonlinear dose-response
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=homocysteine U-shaped association all-cause mortality cohort nadir" \
--data-urlencode "study_types=cohort study,longitudinal / panel data study" \
--data-urlencode "human=true" \
--data-urlencode "sample_size_min=1000" \
--data-urlencode "page_size=50"
```
`medical_mode=true` narrows to top medical journals and guidelines (about 8M documents) when a tier returns too much general literature.
## What to check before you trust it
This is a research summary for qualified human review, not clinical guidance. Nothing here should drive a treatment decision on its own. Keep the citation trail intact so a reviewer can check each statement against its source.
* **Check that both bounds are actually evidenced.** The most common failure is a lower bound with real support and an upper bound asserted from convention. Read the justification for each separately.
* **Reverse causation is the main confounder.** Low values of many biomarkers mark existing illness. If the report does not discuss the sensitivity analyses excluding early deaths and prevalent disease, the U-shape may be an artefact.
* **Check assay comparability.** Ranges from different assays are often not interchangeable — the prompt asks for this, but verify it was answered.
* **Watch for tier disagreement being smoothed over.** If MR says no causal effect and cohorts show a strong association, that conflict is the finding.
## Related
The same tiered method, applied to a target rather than a biomarker.
Pull the nadir ranges and effect sizes into rows you can compute on.
Fan-out, the filter ladder, and the rest of the primitives.
Browse the gallery by persona.
# Monitor new research about a drug, device, or brand
Source: https://docs.consensus.app/use-cases/brand-and-device-monitoring
Track what gets published about a drug, device, or brand, and route only the papers that change something.
## What you get
A recurring brief covering what appeared in the literature about your products, your competitors' products, and the mechanisms behind them — filtered down to the items that matter, with an explicit empty state when nothing does.
## Who it's for
Commercial, medical affairs, and competitive-intelligence teams in life sciences, and consultancies running this on behalf of clients. Also the shape used by companies building literature monitoring into their own product.
## How it works
Brand names are unreliable in the literature — papers name the molecule, the device class, or the mechanism. Query all of them: brand, generic or molecule name, device category, and the underlying mechanism.
Once you know which authors publish in the space, track their names as queries in their own right. Shifts in who publishes often precede shifts in what is published.
Set `year_min` and `month_min` to the last run. Diff on `doi` against stored state so the brief contains only what is new.
For each new paper, say what it implies — a competitor's program stage, a safety question, a comparator result. Flag changes in venue, geography, or collaborator.
Route safety findings and head-to-head comparisons to a human immediately. Everything else can wait for the weekly brief.
## The API call
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=drug-eluting stent restenosis outcomes comparison" \
--data-urlencode "year_min=2026" \
--data-urlencode "month_min=8" \
--data-urlencode "exclude_preprints=false" \
--data-urlencode "page_size=100"
```
Useful narrowing for this workflow:
| Parameter | Why it helps here |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `medical_mode=true` | Restricts to top medical journals and guidelines when general literature is too noisy |
| `country` | Region-specific briefs for local commercial teams |
| `journal_name` | Watch a specific venue where your category publishes |
| `sjr_max=1` | Top-quartile only, when volume is high and you need the papers that will be cited |
| `exclude_preprints=false` | Keep preprints — early signals often surface there first |
## Turning it into a product
Several customers resell this. If that is the shape you are building:
* **The API is per-integration, not per-user.** One `x-api-key` covers your service; your own users never need Consensus accounts.
* **Size the plan against request volume.** A watchlist of 50 entities refreshed weekly, paginated, runs into the thousands of requests a month.
* **Cache on the full parameter set.** Two clients watching overlapping mechanisms will issue near-identical queries.
* **Pass the `url` through.** Every result links back to the paper on Consensus, which is the citation trail your users need.
## What to check before you trust it
* **Brand-name-only watchlists miss most of the literature.** Verify by searching the molecule and mechanism separately and comparing volume.
* **Alert when a run returns nothing across the whole watchlist.** That is usually a broken job, not a quiet week.
* **Short brand names collide.** Spot-check any entity producing unusually high volume for unrelated hits.
* **The brief must have an empty state and use it.** A monitor that always finds five things trains people to ignore it.
## Related
The engineering underneath: pagination, diffing, backoff.
Go deep on a mechanism the monitor surfaced.
Diff-against-last-run and the rest of the primitives.
Browse the gallery by persona.
# Verify that every citation is real and supports its claim
Source: https://docs.consensus.app/use-cases/citation-verification
Verify every reference in a document actually exists, then confirm each one says what the text citing it claims.
## What you get
A per-reference verdict: verified with a DOI, metadata mismatch, or not found. Then, for the ones that exist, a second verdict on whether the paper actually supports the sentence citing it.
Two different failures, caught separately. A fabricated reference is obvious once you look. A real paper cited for something it never claimed is the one that survives review.
## Who it's for
Anyone reviewing AI-assisted drafts, grant text, vendor reports, or student submissions. Also worth wiring into a submission pipeline if you handle volume.
## The prompt
```text theme={null}
You are a reference-checking specialist. You are auditing a bibliography for
fabricated and misapplied citations using Consensus.
Stage 1 — does the reference exist?
For each reference in the list below:
1. Search Consensus for the exact title, verbatim, in quotes.
2. Compare what comes back against the reference as given, field by field:
title, first author surname, journal, and publication year.
3. Assign a status:
- VERIFIED — title matches near-exactly and the first author, journal, and
year all agree. Record the DOI you matched.
- METADATA MISMATCH — a paper with this title exists, but one or more of
author, journal, or year is wrong. Say which field and give the correct value.
- NOT FOUND — no near-title match. Before concluding this, retry once with
the distinctive noun phrase from the title rather than the full string.
Do not mark a reference VERIFIED on topical similarity. A different paper about
the same subject is NOT a match — that is the exact failure being hunted here.
Stage 2 — does it support the sentence?
For each VERIFIED reference, take the sentence in the document that cites it and
search Consensus for that claim. Then judge:
- SUPPORTS — the paper substantiates the sentence. Quote the supporting text.
- DOES NOT SUPPORT — the paper exists and is on-topic but does not make this
claim. Say what it does claim instead.
- CANNOT TELL — the abstract is insufficient to judge. Say what you would
need to read.
Output two tables, one per stage. End with counts: verified, mismatched,
not found, and how many verified references fail to support their sentence.
References:
[PASTE THE BIBLIOGRAPHY]
Document text (for stage 2):
[PASTE THE TEXT, or omit to run stage 1 only]
```
## How it works
A real paper returns a near-exact `title` match. A fabricated one returns only loose topical neighbours — which is precisely why the prompt forbids accepting topical similarity as a match.
Requiring `publish_year`, `journal_name`, and first author to agree before marking anything verified turns a soft call into a mechanical one. Hallucinated references very often pair a real title with a wrong year or journal.
Long titles with subtitles sometimes miss on the full string. A single retry on the distinctive noun phrase prevents false `NOT FOUND` verdicts without opening the door to loose matching.
In AI-assisted drafts, most references exist. The failure that matters is a genuine paper attached to a claim it never made.
## The API equivalent
Stage 1, per reference — search the title and compare metadata:
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=Effects of intermittent fasting on cardiometabolic risk factors" \
--data-urlencode "page_size=5"
```
Match on a normalized `title` comparison, then assert `publish_year`, `journal_name`, and the first entry of `authors`. Record `doi` on success.
Stage 2 — search the citing claim and read the excerpt:
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=intermittent fasting LDL cholesterol reduction magnitude" \
--data-urlencode "include_full_text_chunks=true" \
--data-urlencode "page_size=10"
```
`include_full_text_chunks` requires a paid plan or an Enterprise API key and currently covers open-access papers. Stage 1 needs none of it — title and metadata matching works on every plan.
## What to check before you trust it
* **A `NOT FOUND` is not proof of fabrication.** Book chapters, conference proceedings, grey literature, and very recent papers may sit outside coverage. Treat it as "needs a human look", not a verdict.
* **Beware near-identical titles.** Some fields have several papers with nearly the same title across different years. The author and year assertions are what keep these apart.
* **Run stage 1 alone first.** It is cheap, needs no full text, and usually surfaces the worst problems on its own.
* **Do not auto-reject on this output.** It is a triage tool that tells a human where to look.
## Related
The upstream fix: get real citations attached as you write.
The same verification discipline, applied to claims that ship.
Fan-out, the filter ladder, and the rest of the primitives.
Browse the gallery by persona.
# Substantiate a product claim with published evidence
Source: https://docs.consensus.app/use-cases/claim-substantiation
Build the evidence file behind a claim before it ships — including what contradicts it.
## What you get
A claim-by-claim substantiation file: the peer-reviewed evidence supporting each claim, the evidence against it, a defensibility grade, and suggested wording the evidence actually supports.
## Who it's for
Product, brand, regulatory, and R\&D teams in consumer goods, sports and performance products, supplements, and devices — plus the consultancies who advise them.
## The prompt
```text theme={null}
You are a claims substantiation analyst. You are assembling the evidence file
behind product claims before they go to market.
Claims:
[LIST THE CLAIMS, ONE PER LINE]
Product context: [WHAT IT IS, WHO USES IT, HOW]
For each claim:
1. Split it into testable parts. "Reduces injury risk and improves comfort" is
two claims with different evidence bases — never assess them together.
2. State each part as a proposition naming the population, the intervention or
product attribute, the comparator, and the outcome measure.
3. Search Consensus for supporting evidence. Require human studies with a
control condition and a realistic sample size. Note the exact population
studied — trained athletes are not recreational users, and lab protocols are
not real-world use.
4. Search separately for contradicting evidence, using the negative phrasing.
Finding the contradicting paper yourself is far cheaper than a competitor
or a regulator finding it.
5. Check whether the effect was measured directly or inferred from a surrogate.
A claim about injury risk supported only by a biomechanical proxy is a
different claim.
Grade each part:
STRONG — multiple controlled human studies, consistent direction, population
matches our users.
QUALIFIED — evidence exists but is limited by population, sample size, design,
or reliance on a surrogate outcome. Write the narrower claim it supports.
UNSUPPORTED — no adequate evidence found. Say what you searched.
CONTRADICTED — the weight of evidence points the other way. Give the citation.
For every QUALIFIED and UNSUPPORTED part, propose the wording the evidence does
support, and say what study would be needed to support the original.
Output: Claim part | Grade | Population studied | Direct or surrogate outcome |
Supporting citations | Contradicting citations | Suggested wording.
```
## The API call
Demand controlled human evidence at a realistic size:
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=forefoot bending stiffness running economy oxygen cost" \
--data-urlencode "human=true" \
--data-urlencode "controlled=true" \
--data-urlencode "sample_size_min=15" \
--data-urlencode "study_types=rct,non-randomized experimental study" \
--data-urlencode "page_size=50"
```
Then run the negative pass:
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=footwear stiffness no effect running economy null finding" \
--data-urlencode "human=true" \
--data-urlencode "controlled=true" \
--data-urlencode "page_size=50"
```
| Parameter | Why it matters here |
| ----------------- | -------------------------------------------------------------------------------------- |
| `human=true` | Animal and in vitro evidence rarely substantiates a consumer claim |
| `controlled=true` | Uncontrolled studies will not survive review |
| `sample_size_min` | Filters the underpowered studies that make weak claims look supported |
| `sjr_max` | Restrict to higher-quartile journals when the field has a large promotional literature |
| `domain` | Keeps technical terms in the right field |
## What to check before you trust it
This is an evidence file for legal, regulatory, and marketing review — not a compliance sign-off. Requirements differ by market and claim type, and a human with that jurisdiction's expertise makes the final call.
* **Check the population column on every row.** The most common substantiation failure is real evidence from a population that is not your customer.
* **Direct versus surrogate outcome is load-bearing.** A biomechanical proxy does not substantiate an injury-reduction claim, however strong the correlation.
* **Confirm the negative pass actually ran.** If there are no contradicting citations anywhere in the file, it was skipped — null findings exist in almost every applied field.
* **Take the suggested wording seriously.** The narrower claim is usually still a good claim, and it is the one you can defend.
## Related
Pull the effect sizes behind the claim into a comparable table.
The human-subjects evidence behind a product decision.
The filter ladder and the rest of the primitives.
Browse the gallery by persona.
# Grade a set of papers with your own evidence rubric
Source: https://docs.consensus.app/use-cases/evidence-grading-rubric
Apply your organization's standard for what counts as good evidence, consistently, across every paper on a topic.
## What you get
Every paper scored against the same rubric, with the reason for each score and the evidence behind it — so two people asking the same question a month apart get comparable answers.
This is what our highest-volume self-serve user does: a biotech founder running a custom evidence-grading prompt over hundreds of searches.
## Who it's for
Any team with an internal standard for evidence quality — biotech, clinical, nutrition, or research operations — where "is this well-supported?" currently depends on who you ask.
## The prompt
```text theme={null}
You are an evidence assessor applying a fixed grading rubric.
Question: [THE CLAIM OR TOPIC]
Rubric (score every paper on all three axes):
A. Design strength
5 — meta-analysis or systematic review of controlled trials
4 — randomized controlled trial
3 — prospective cohort or well-controlled non-randomized study
2 — cross-sectional, case-control, or retrospective
1 — case report, in vitro, or animal only
B. Execution quality
5 — adequately powered, pre-registered, low attrition, blinded where possible
3 — reasonable but with named limitations
1 — serious limitations: underpowered, high attrition, no control
C. Relevance to our question
5 — same population, same exposure, same outcome
3 — differs on one dimension; say which
1 — indirect or surrogate outcome only
Rules:
- Score from what the paper reports, not from journal or author reputation.
- Where a paper does not report enough to score an axis, mark it NOT REPORTED
rather than assuming the middle. Do not average around missing information.
- A high design score does not raise the execution score. A large RCT executed
badly is a 4 and a 1, and that combination is the useful signal.
- State the single fact that most constrains each score.
Output: Paper | DOI | A | B | C | Overall | Limiting factor | Supporting quote.
Then: the highest-graded evidence, the strongest contradicting evidence, and
what an ideal study would need to settle the question.
```
## Getting a rubric worth applying
Design, execution, and relevance fail independently. A single 1–5 "quality" score hides which one is the problem and makes the grades incomparable across topics.
"Well-controlled" means different things to different readers. Naming a real paper at each level makes the scale reproducible.
Journal and author reputation are already available as `sjr_best_quartile` and `citation_count`. Keep them as separate metadata, not smuggled into the quality score.
Papers that omit a detail are common. Scoring them at the midpoint quietly inflates the evidence base.
## Feeding it good candidates
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=omega-3 supplementation cardiovascular events" \
--data-urlencode "study_types=meta-analysis,systematic review,rct" \
--data-urlencode "human=true" \
--data-urlencode "sample_size_min=100" \
--data-urlencode "page_size=50"
```
Paid plans return `study_type` and `takeaway` on each result, which give the grader a head start on axis A. `include_full_text_chunks=true` is what makes axis B possible at all — execution quality is rarely visible in an abstract.
## Audit requirements
Follow the [grounding rules](/use-cases/best-practices#grounding-and-auditability). Record the rubric version alongside every graded set: a rubric edit makes old grades incomparable, and teams discover this months later when two reports disagree.
## What to check before you trust it
* **Check the score distribution.** If nothing scores low, the rubric is being applied generously — real literature has a spread.
* **Grade five papers by hand first** and compare. Disagreements almost always point at an ambiguous rubric level, not a model failure.
* **Watch for axis contamination.** If design and execution scores move together on every paper, they are not being assessed separately.
* **Execution scores from abstracts are unreliable.** Without full text, mark axis B as low-confidence rather than guessing.
## Related
Tiered grading applied to one biomarker question.
Split preclinical from human evidence before grading it.
Grounding rules and the five primitives.
Browse the gallery by persona.
# Extract numbers and formulas from full-text papers
Source: https://docs.consensus.app/use-cases/extract-values-from-full-text
Pull numbers, formulas, and parameters out of papers with their measurement conditions attached.
## What you get
Rows you can compute on: one row per extracted value, each carrying the conditions it was measured under and the excerpt it came from. Not a summary of papers — a dataset built from them.
This is what teams reach for when abstracts are not enough: an aerodynamics group extracting mathematical formulas from full texts, a materials team collecting performance figures across test conditions, a clinical team pulling effect sizes for a meta-analysis.
## Who it's for
Engineering and physical-science R\&D, and any research team assembling a quantitative dataset from published work.
Full-text excerpts (`include_full_text_chunks`) require a paid plan or an Enterprise API key, and currently cover open-access papers. Everything else on this page — search, filtering, metadata — works on any plan.
## How it works
Decide every column up front: the value, its units, the conditions it was measured under, the method, the sample or specimen, and the source. A schema settled mid-run produces a table you cannot pivot.
Excerpts are selected for relevance to your `query`. Searching the paper's topic returns introduction paragraphs; searching the measurement returns the results section. This single choice does more for extraction quality than anything else.
Without `domain`, technical terms pull in unrelated biomedical hits. `domain=mat,eng,phys,chem` is the difference between a usable and an unusable result set.
A number without its test conditions is not comparable to another number. A number without its excerpt is not auditable. Both travel with the row.
Use different values for the two. Conflating them silently biases every downstream count.
## The API call
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=turbulent boundary layer separation drag coefficient measured values" \
--data-urlencode "domain=eng,phys,mat" \
--data-urlencode "include_full_text_chunks=true" \
--data-urlencode "page_size=100"
```
Each result's `full_text_chunks` holds query-relevant excerpts. Pair with metadata already on the result — `doi`, `title`, `publish_year`, `journal_name`, `url` — so each extracted row carries its provenance.
## The extraction prompt
```text theme={null}
You are a data extraction specialist building a structured dataset from papers.
Schema — every row must have all of these, or an explicit marker for why not:
value | units | quantity measured | measurement conditions | method or
apparatus | specimen or sample | source DOI | source excerpt
Rules:
1. Extract only values that appear in the excerpt you were given. Never infer,
convert, or interpolate a value that is not written there.
2. Every value keeps the conditions it was measured under. If the excerpt gives
a number without its conditions, record it as CONDITIONS NOT REPORTED — do
not assume standard conditions.
3. Preserve the original units. Add a converted column if needed, but never
overwrite the original.
4. Use NOT REPORTED when the paper does not give a field, and NOT EXTRACTED
when the excerpt was insufficient. These are different and must not be merged.
5. Copy the source excerpt verbatim into its column. Every row must be
checkable against it without reopening the paper.
6. For formulas, reproduce the expression exactly and define every symbol as
the paper defines it. If a symbol is defined elsewhere in the paper and not
in your excerpt, mark it undefined rather than guessing.
Output the rows as CSV. Follow it with a list of papers you could not extract
from and why.
```
## What to check before you trust it
* **Spot-check five rows against their excerpts.** The excerpt column exists precisely so this takes two minutes rather than an afternoon.
* **Watch for silent unit assumptions.** Values converted without an original-units column are the most common corruption in extracted datasets.
* **Check the CONDITIONS NOT REPORTED rate.** If it is near zero, conditions are being assumed rather than read.
* **Coverage is not uniform.** Full-text excerpts currently cover open-access papers, so a closed-access subfield will be under-represented. Check whether your topic skews that way before treating the dataset as complete.
## Related
Turn extracted evidence into a defensible claim file.
The same extraction discipline inside a clinical evidence review.
Excerpt-first extraction and the rest of the primitives.
Browse the gallery by persona.
# Find published work on a failure or degradation mechanism
Source: https://docs.consensus.app/use-cases/failure-mode-scan
Check whether a defect you are seeing is a known mechanism with a published cause, before you spend a quarter rediscovering it.
## What you get
What the literature already reports about your failure mode: proposed mechanisms, the conditions that drive it, published mitigations, and how others detected it — with the citations to hand to your reliability team.
## Who it's for
Reliability engineers, failure analysis teams, and process integration groups in semiconductor, automotive, and aerospace manufacturing.
## Why check the literature first
Failure and degradation mechanisms are heavily studied academically, often more thoroughly than any single company can afford internally. Checking whether a mechanism is known costs an afternoon; rediscovering it costs a quarter. The literature also gives you the vocabulary — knowing the accepted name for what you are seeing makes every subsequent search work.
## How it works
Search what you actually see — the morphology, where it appears, what conditions precede it. Searching your suspected cause finds papers confirming that cause, whether or not it is right.
Once results suggest a named mechanism, search that name directly. Field-standard terminology returns far better results than descriptive language, and you rarely know it at the start.
The same physical mechanism often appears under a different name in another field. Electromigration, fretting, delamination, and thermal fatigue all cross industries. Widen `domain` deliberately once before narrowing.
Both matter. A published mitigation that did not work saves you from trying it.
How other groups measured the mechanism tells you what to instrument, and is often the fastest thing to act on.
## The API call
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=electromigration void nucleation copper interconnect current density" \
--data-urlencode "domain=eng,phys,mat" \
--data-urlencode "include_full_text_chunks=true" \
--data-urlencode "page_size=50"
```
Add `year_min` when the relevant process generation is recent — failure behaviour is often node- or generation-specific, and older literature may describe a materially different structure.
## What to check before you trust it
* **Confirm the geometry and scale match.** A mechanism documented at one dimension or process node may behave differently at another, and papers do not always make the regime explicit.
* **Check the accelerated-test conditions.** Most reliability literature uses accelerated ageing. The extrapolation back to operating conditions is where the assumptions hide.
* **A mechanism that matches your symptoms is a hypothesis.** Several mechanisms produce similar signatures; use the literature to design the discriminating test, not to close the investigation.
* **Coverage skews toward open access.** Much of this literature sits in closed conference proceedings, so treat a thin result as inconclusive rather than as evidence the mechanism is unstudied.
## Related
Once you know the mechanism, compare materials that resist it.
Conditions that avoid the mechanism entirely.
Fan-out and merge, and the rest of the primitives.
Browse the gallery by persona.
# Find NIH grants for a research idea
Source: https://docs.consensus.app/use-cases/grant-finder
Position a research idea against the literature, map it to the right NIH institutes and study sections, and surface NOSIs, open FOAs, and funded overlap.
## What you get
An editable Word document scoping the NIH funding landscape for one research idea: draft Significance and Innovation language built from real gap quotes, a ranked list of institutes actually funding this work, the study sections that would review it, any active Notices of Special Interest, and mechanism recommendations matched to career stage *and* project scope.
Consensus ships this as a packaged skill. It covers NIH only — not PCORI, DOD CDMRP, VA Merit, or foundations — and says so up front rather than implying broader coverage.
## Who it's for
Clinical and translational researchers scoping funding for an idea, from trainees through established investigators. Also mentors and research-development offices advising them.
## Phase 1 — Intake
Set expectations first, then ask three questions:
1. **Career stage** — trainee (F31/F32/T32), early-career faculty (K01/K08/K23/K99-R00/R21), or established. If established, split mid-career (has a K or first R01 → R01/R21/R34) from senior (R01/R35/P01/U01).
2. **Preliminary data** — starting from scratch, pilot evidence available, or resubmission. If resubmission, ask whether it was scored or triaged; that changes the strategic advice entirely.
3. **Institutional environment** — major research university, academic medical center, or another setting (smaller/community-based, or VA/military-affiliated). This affects which mechanisms are realistic and how to frame the Environment section.
## Phase 2A — Positioning analysis, five searches
The goal is **not** to answer "is this novel?" It is to produce **positioning language the researcher can paste into a grant**. Each search builds a different part of the argument. Run them sequentially — see [rate limits](/use-cases/best-practices#rate-limits-and-result-caps).
| # | Facet | What it produces |
| - | ----------------------------------- | ---------------------------------------------------- |
| 1 | What's established | The "what is known" setup in Significance |
| 2 | The problem's importance | Prevalence, burden, disparities — the "why now" |
| 3 | Current approaches and limits | What exists today, and therefore what's insufficient |
| 4 | The method in adjacent contexts | Applied elsewhere = validation; nowhere = novelty |
| 5 | **What researchers say is missing** | The highest-value search — the gap, in their words |
Search 5 matters most. Look explicitly for language like *"future research should"*, *"remains unclear"*, *"no studies have"*, *"limited evidence"*, *"critical gap"*. Pull **3–5 of these with full attribution** — they become the backbone of the positioning argument, because they let the researcher show reviewers that the field itself recognizes the gap.
### Build the narrative, don't list counts
Deduplicate across all five facets by DOI first; papers found in multiple facets are high-signal. Then write 2–3 paragraphs the researcher can adapt directly:
> **Paragraph 1** — "The field has established \[X, Y, Z from searches 1–2]. The burden is significant because \[stakes from search 2]."
>
> **Paragraph 2** — "Current approaches include \[search 3], but they fall short because \[gap quotes from search 5]. Specifically, \[quote 1] and \[quote 2]."
>
> **Paragraph 3** — "This project proposes \[the idea]. \[Search 4] suggests the approach is feasible, and the gap above shows it has not been applied to \[this population]. This is a \[novel/underexplored] intersection."
**Evidence-depth gate:** aim for at least 3 directly relevant papers per facet and 15–20 unique cited papers overall — but only where the returned evidence supports it. Never add a marginal paper to pad the bibliography. Keep gap quotes under 25 words each and paraphrase the surrounding context.
## Phase 2B — Institute and grant discovery
The NIH RePORTER API requires **POST**, so a GET-only fetch will not work:
```bash theme={null}
CURRENT_YEAR=$(date +%Y)
FY_RANGE="[$((CURRENT_YEAR-3)), $((CURRENT_YEAR-2)), $((CURRENT_YEAR-1)), $CURRENT_YEAR]"
curl -s -X POST "https://api.reporter.nih.gov/v2/projects/search" \
-H "Content-Type: application/json" \
-d '{
"criteria": {
"advanced_text_search": {
"operator": "and",
"search_field": "projecttitle,terms,abstract",
"search_text": "NARROW KEYWORDS"
},
"fiscal_years": '"$FY_RANGE"',
"include_active_projects": true
},
"limit": 20, "offset": 0,
"include_fields": ["ProjectTitle","AbstractText","ActivityCode","AwardAmount","FiscalYear","PrincipalInvestigators","Organization","OpportunityNumber","AgencyIcAdmin","ProjectNum","StudySection"]
}'
```
Run a narrow AND search and a broad OR search, then deduplicate by `project_num`. Compute the fiscal-year window dynamically so it never goes stale.
**Search-quality gate.** Valid JSON is not a usable portfolio. If fewer than half the returned projects are substantively relevant, refine the keywords and re-run rather than ranking institutes off noise. If no focused search yields at least 5 relevant projects, proceed but label all institute conclusions preliminary.
### The most actionable finding
Produce **two separate institute rankings** and explain any gap between them:
1. **Portfolio volume** — tally `agency_ic_admin.abbreviation`.
2. **Design and mission fit** — which institutes fund projects similar in population, methodology, clinical setting, and intended outcome.
Do not simply recommend the biggest number.
> "NIAID has the largest raw HSV portfolio, but most projects are basic virology or therapeutic development. NICHD has fewer awards but the closest methodological overlap with multicenter pediatric clinical prediction research; NICHD is therefore the stronger primary fit and NIAID a plausible secondary assignment."
Then tally `study_section` values to identify the review panels, extract `opportunity_number` values starting with `NOT-` to find NOSIs, and match mechanisms on **both** career stage and project scope — a multi-site study does not fit in a 2-year \$275K R21, and a pilot does not need an R01.
## Phase 3 — The document
Nine numbered sections, in order, none of which may be dropped for sparse data: Executive Summary · Your Positioning in the Field · Where NIH Is Funding This Work · Recommended Funding Opportunities · Similar Funded Research · Where This Work Gets Reviewed · Strategic Recommendations & Next Steps · References · Audit Log.
If study-section data is unavailable, the section still appears and explains the limitation. Missing data never authorizes removing a required section or renumbering later ones.
**Always include a program officer recommendation** — it is the single most valuable piece of advice for any applicant. POs confirm fit, suggest the right FOA, and flag problems before submission.
Verify submission dates against a live NIH page rather than trusting a static table, and note which upcoming cycle is realistic given how much work remains.
Budget ranges, submission dates, and eligibility change. Anything drawn from reference knowledge rather than a tool call in this session must be labelled as such and verified against the current official announcement before the researcher acts on it.
## Audit requirements
Follow the [grounding rules](/use-cases/best-practices#grounding-and-auditability). This workflow needs two audit tables — Consensus searches (search #, facet, query, papers found, papers shown, papers cited, status) and RePORTER searches (type, keywords, total/returned, relevant projects used, status), including every refinement query. Add NOSI fetch outcomes where applicable.
Distinguish three numbers explicitly: **found by Consensus**, **shown to us**, and **cited in this report**. If a plan cap was detected, say so — sparse results on a facet may be a plan ceiling rather than a genuine gap, and the researcher needs to know which.
## What to check before you trust it
* **Check the gap quotes are real quotes**, with named attribution and a working link. Unexplained sentence fragments are the failure mode here.
* **Read the institute reasoning, not just the ranking.** The volume-versus-fit distinction is the most actionable output; if the report just names the biggest institute, that analysis was skipped.
* **Verify every FOA and NOSI** against its official NIH page before acting. Constructed links must not be presented as verified.
* **A sparse RePORTER portfolio is information.** It may mean an unfunded niche — an opportunity or a warning, depending on why.
## Related
The deeper review workflow behind the positioning analysis.
Once the grant is funded, cite the same way.
Rate limits, grounding rules, and the five primitives.
Browse the gallery by persona.
# Find a real citation for every claim in a draft
Source: https://docs.consensus.app/use-cases/ground-a-manuscript
Paste a draft section and get every empirical claim matched to a real, verifiable paper — or flagged as unsupported before a reviewer finds it.
## What you get
Your draft back, claim by claim, with a real citation attached to each one — journal, year, DOI, and a link to the paper on Consensus. Claims the literature does not support come back flagged rather than quietly cited to something adjacent.
This is the most common thing people do with Consensus MCP. Researchers writing with an AI assistant report going from citations they could not verify at all to a draft where nearly every claim checks out.
## Who it's for
Anyone drafting with an LLM in the loop: PhD students writing a thesis chapter, clinicians writing a discussion section, postdocs turning results into a manuscript. Works in whatever you already write with — Claude, ChatGPT, Claude Code.
## The prompt
Paste your draft section after this. Works as-is in any MCP client.
```text theme={null}
You are a research librarian and evidence synthesis specialist.
Task:
For the draft text below, find a real peer-reviewed citation for every empirical
claim, using Consensus. Do not write new prose. Do not improve my argument.
Procedure, per claim:
1. Extract the claim as a standalone proposition. Name the population, the
exposure or intervention, and the outcome. If any of those three is missing
from my text, say so rather than assuming one.
2. Search Consensus for it. Run at least three phrasings covering synonyms and
the terminology the relevant field actually uses.
3. Prefer the strongest available design: meta-analyses and systematic reviews
first, then randomized trials, then observational studies. Note which tier
you ended up in.
4. Read the abstract and the key takeaway. Confirm the paper supports the claim
as I stated it, not merely the general topic.
Classify every claim as exactly one of:
- SUPPORTED — a paper supports it as stated. Give the citation and one quoted
sentence or takeaway showing why.
- PARTLY SUPPORTED — the evidence supports a narrower version. Give the
citation and write the narrower claim I should use instead.
- CONTRADICTED — the weight of evidence points the other way. Give the citation.
- NO EVIDENCE FOUND — you searched and found nothing on point. Say what you
searched. Do not substitute a loosely related paper.
Rules:
- Never cite a paper you did not retrieve through Consensus in this session.
- Do not merge two claims to make one citation fit.
- Common-knowledge and methodological statements need no citation. Skip them
and say you did.
Output a table: Claim | Verdict | Citation (authors, year, journal, DOI) |
Evidence quote | Suggested rewording if needed.
Draft text:
[PASTE YOUR DRAFT SECTION]
```
## How it works
Most bad citation matching happens because a sentence carrying three claims gets one citation. Forcing each claim into a standalone proposition with a named population, exposure, and outcome is what makes the search specific enough to be checkable.
A single phrasing is one search. Three or more across synonyms and field-specific terminology is the difference between "no evidence found" and finding the paper that exists.
Knowing you ended up citing an observational study rather than a trial changes how you should word the sentence. Ask for the tier and you get that for free.
The `PARTLY SUPPORTED` bucket is where most of the value is — it turns an overclaim into a defensible sentence instead of forcing a binary keep-or-cut decision.
## The API equivalent
If you are building this into a writing tool rather than running it in a chat, search per extracted claim and keep the design tier explicit:
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=resistance training muscle strength adults over 60" \
--data-urlencode "study_types=meta-analysis,systematic review,rct" \
--data-urlencode "human=true" \
--data-urlencode "page_size=20"
```
Each result carries `title`, `authors`, `journal_name`, `publish_year`, `doi`, `citation_count`, and `url`. On paid plans, `study_type` and `takeaway` come back too — `takeaway` is what you show the writer as the evidence quote.
## What to check before you trust it
* **`NO EVIDENCE FOUND` is a real answer.** If you get none of them across a whole section, the prompt is being too accommodating — the model is stretching papers to fit. Re-run and insist on the distinction.
* **Check one citation by hand per section.** Open the `url` and confirm the paper says what the table claims. Calibrate once, then trust the pattern.
* **Watch for topic-level matches.** A paper about the right subject that never tested your specific claim is the most common failure. The requirement to quote a supporting sentence is what catches it.
* **The tier matters for wording.** A claim supported only by observational evidence should not be written as though a trial established it.
## Related
The other half of the job: verify the references you already have.
Make this repeatable instead of pasting the prompt every time.
Fan-out, the filter ladder, and the rest of the primitives.
Browse the gallery by persona.
# Screen thousands of target-disease pairs for evidence
Source: https://docs.consensus.app/use-cases/high-throughput-screening
Pull literature evidence for every pair in a large matrix — the batch workload that breaks most retrieval APIs.
## What you get
Evidence attached to every cell of a screening matrix. Not interactive search: a pipeline that walks tens of thousands of pairs, retrieves the literature for each, and produces a structured result you can rank and filter.
## Who it's for
Computational biology and platform teams running systematic screens, and anyone whose "search" is really a batch job with a six-figure cell count.
## How Phylo runs it
[Phylo](https://consensus.app/home/community-voices/phylo/) is an AI-native IDE for biology built by researchers from Stanford. One internal team uses the Consensus API to screen roughly **20,000 targets across hundreds of diseases**, pulling literature evidence for every target-disease pair.
> "It's very robust, with almost zero errors. It gives you genuinely useful results, and it embeds into a high-throughput agentic workflow easily."
>
> — **Kexin Huang**, Co-founder & CEO, Phylo
Literature is not a side feature of that product — it is underneath nearly everything it does:
> "Even in analysis tasks, there's literature research underneath. For single-cell annotation, you need to find marker genes. To compare a paper's findings against your own dataset, you need literature. To brainstorm a hypothesis, to understand a mechanism of action for a particular drug and disease, all of this requires a large volume of literature. That's why we spent so much time making sure our literature search was the highest quality."
>
> — **Kexin Huang**, Co-founder & CEO, Phylo
## Building the screen
One query template crossed with two entity lists is auditable and cheap to change. Hundreds of hand-written queries are neither.
"Is there any literature linking this target to this disease" and "is there strong human evidence" are different screens with different filters. Pick one and hold it constant, or your cells are not comparable.
This is where batch pipelines fail. The ceiling is per user, per second — see [rate limits](/use-cases/best-practices#rate-limits-and-result-caps). Build a bounded work queue with backoff and jitter before you scale the matrix, not after.
Screens have enormous overlap — the same target appears against hundreds of diseases. Cache on every parameter with a short TTL and you cut a large fraction of the calls.
Paper count is a poor signal. Weight by study design, recency, and whether the evidence is human. A cell with one strong trial outranks a cell with forty in vitro papers.
A pair with no literature is a finding — it is either a genuine gap worth investigating or a terminology problem in your template. Distinguish them by spot-checking.
```python theme={null}
def screen(targets, diseases, template, search):
for target in targets:
for disease in diseases:
query = template.format(target=target, disease=disease)
body = search(query=query, human=True, page_size=25)
yield {
"target": target,
"disease": disease,
"n": len(body["results"]),
"top": body["results"][:5], # keep DOIs for provenance
}
```
Pace the loop to one search per second and build in backoff, rather than firing cells in parallel.
## What to check before you trust it
* **Validate the template on 50 cells first.** A template that produces noise at cell 50 produces noise at cell 50,000, expensively.
* **Watch for entity-name collisions.** Short gene symbols and common disease words pull in unrelated literature. Spot-check the highest-volume cells — anomalously high counts usually mean an ambiguous name.
* **Distinguish a plan cap from a real result.** If responses report finding more than they returned, your matrix is measuring your ceiling, not the literature.
* **Alert when a whole run returns nothing.** Silence looks identical to a broken job.
## Related
The interactive counterpart to this batch pattern.
Re-run a screen on a cadence and report only the delta.
Exhaustive sweep, rate limits, and the five primitives.
Browse the gallery by persona.
# Find human-factors evidence for a design decision
Source: https://docs.consensus.app/use-cases/human-factors-evidence
Pull the biomechanics, ergonomics, and usability research behind a product or workstation choice, before the decision gets defended after the fact.
## What you get
The published human-subjects evidence for a design decision: what has been measured, in whom, under what conditions, with what effect size — and where the evidence simply does not exist for your population.
## Who it's for
Product designers, human factors and ergonomics engineers, sports-science and footwear R\&D teams, and occupational health groups. Corporate science teams doing kinesiology and biomechanics research sit squarely here.
## Why it belongs to human-subjects rules
This is the corner of applied R\&D where the evidence is about people, so the filters that matter are the clinical ones: `human`, `controlled`, and `sample_size_min` do more for result quality here than any materials or engineering filter.
## How it works
Not "what does the research say about midsole foam" but "does increased midsole stiffness reduce metabolic cost in recreational runners". Named population, named intervention, named measurable outcome.
Set `human=true`, `controlled=true`, and a realistic `sample_size_min`. Biomechanics studies are often very small; a threshold around 15 to 20 filters out the least informative work without emptying the result set.
Trained athletes are not recreational users. Young male university students are not the general population. This literature has a well-known sampling skew, so read the population column before the finding.
A change in a gait parameter on a treadmill is not a change in injury rate in the world. Track which you have — this is where most overclaiming in this field starts.
Run the negative phrasing. In biomechanics, small studies with positive findings publish more readily than small studies without.
## The API call
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=midsole longitudinal bending stiffness running economy metabolic cost" \
--data-urlencode "human=true" \
--data-urlencode "controlled=true" \
--data-urlencode "sample_size_min=15" \
--data-urlencode "domain=psych,eng,med" \
--data-urlencode "page_size=50"
```
`domain=psych,eng,med` covers most of this literature — human factors work is split across psychology, engineering, and sports medicine, and restricting to one loses a third of it.
## What to check before you trust it
* **Read the sample description on every study.** Population mismatch is the dominant failure mode in this literature, and it is rarely visible in the abstract's conclusion.
* **Check effect size, not significance.** A statistically significant 1% change in a lab measure may be irrelevant to a design decision.
* **Watch for surrogate outcomes.** Comfort ratings, gait parameters, and injury rates are three different claims, and only the last supports an injury-reduction statement.
* **Small samples dominate.** Treat any single study as provisional; look for replication before it drives a design commitment.
## Related
Turn the evidence into a claim you can defend publicly.
Score the studies consistently before deciding.
Filter ladder and the rest of the primitives.
Browse the gallery by persona.
# Find the leading investigators in an indication
Source: https://docs.consensus.app/use-cases/investigator-mapping
Rank the authors publishing most in a therapeutic area, split by region and by recent versus lifetime output.
## What you get
A ranked investigator list with paper counts, representative citations, recency, and region — built from the literature rather than from whoever your team already knows.
## Who it's for
Medical affairs selecting advisory boards and speakers, clinical operations shortlisting trial sites, and business development mapping who owns a space.
Consensus returns **author names**, not affiliations, institutions, or contact details. This produces a ranked name list you then join to a CRM, an institutional directory, or a trial registry. Treat it as the discovery step, not the whole workflow.
## How it works
Fan out across the indication, its mechanisms, its endpoints, and its main comparators. Paginate — emerging investigators sit in the long tail, and the top 20 results only ever show you the established names.
Tally every name, weighting by `citation_count`, recency, and `sjr_best_quartile`. Track first and last author positions separately where you can infer them: last author usually signals the lab, first author the person doing the work.
Once by lifetime output, once by output in the last 24 months. The two lists differ substantially, and the second is usually the more actionable — it tells you who is active now rather than who was.
Use `country` to build per-region shortlists. A single global list is rarely what a regional medical team can act on.
Output volume is not fit. Check that their actual work matches the specific question before anyone gets contacted.
## The API call
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=CAR-T therapy relapsed refractory multiple myeloma outcomes" \
--data-urlencode "human=true" \
--data-urlencode "year_min=2023" \
--data-urlencode "country=us,gb,de" \
--data-urlencode "page_size=200"
```
```python theme={null}
from collections import Counter
authors = Counter()
for paper in results:
weight = 1 + (paper.get("citation_count", 0) ** 0.5) / 10
for name in paper.get("authors", []):
authors[name] += weight
```
## What to check before you trust it
* **Name ambiguity is the main failure.** Common surnames merge distinct researchers, and the same person appears under several spellings. Verify anyone you plan to act on.
* **Volume rewards large consortia.** Authors on big multi-site trials accumulate counts without being the intellectual lead. Weight last-author position where you can.
* **Check the recency split before using the lifetime list.** Highly-cited historical names may have left the field entirely.
* **This is a discovery list, not a vetted one.** Conflicts of interest, availability, and current affiliation all need checking elsewhere.
## Related
Keep watching the space and the names in it.
Go deep on the science these investigators are publishing.
Fan-out and merge, and the rest of the primitives.
Browse the gallery by persona.
# Build a reusable literature-review workflow
Source: https://docs.consensus.app/use-cases/literature-review-skill
A repeatable review workflow that picks a search framework, allocates a search budget, and synthesizes findings into a research guide your whole team can run the same way.
## What you get
A **launching pad**, not a finished review: a document that orients a researcher in an unfamiliar field fast enough to start reading confidently. What a generous colleague who knows the field would tell you over coffee — here's the lay of the land, here are the key people, here's how the thinking evolved, read these first.
Consensus ships this as a packaged skill. The workflow below is what it does, so you can run it, adapt it, or rebuild it in Claude Code, Codex, or your own agent framework.
## Who it's for
Research-software engineers, methodologists, and technical researchers who run the same class of review repeatedly. Teams doing this report cutting a review from roughly two days to one.
## Set up the connection
```bash Claude Code theme={null}
claude mcp add --transport http consensus https://mcp.consensus.app/mcp
```
```bash Codex theme={null}
codex mcp add consensus --url https://mcp.consensus.app/mcp
codex mcp login consensus
```
## Phase 1 — Reconnaissance
Run **one** broad exploratory search. Confirm it returned data before going further. Then read the abstracts for:
* The major themes and subfields
* **The terminology researchers actually use** — usually not the phrasing the requester used
* Methodological distinctions that matter here (RCT vs observational, animal vs human)
* Angles the requester probably has not considered
Note citation counts as they come back. A paper with unusually high citations relative to its age is likely foundational — flag it for the priority reading list.
## Phase 2 — Pick a framework
Evaluate **PICO first**; it applies far more broadly than just clinical questions.
| Framework | Use when | Components |
| ------------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| **PICO** (primary) | Health, clinical, behavioural, educational, and most social science questions | Population · Intervention · Comparison · Outcome |
| **SPIDER** | No clear intervention or comparison group — lived experience, attitudes, perceptions | Sample · Phenomenon of Interest · Design · Evaluation · Research type |
| **Decomposition** | The topic is a technology or system rather than a population or behaviour | Core mechanism · Applications · Limitations · Alternatives |
Many real questions span frameworks. "How does social media affect teen mental health" has PICO elements, qualitative elements, and technology elements. Pick a primary for structure and say which components borrow from elsewhere — the goal is clarity, not orthodoxy.
Name the chosen framework explicitly, show how the topic maps to each component, and say in one sentence why you picked it over the alternatives.
## Phase 3 — Confirm before spending the budget
Stop and check in. Output a scannable summary:
1. **What the literature shows** — 3–4 sentences on themes, terminology, what is well-studied, what is contested.
2. **Framework mapping table** — one row per component, each proposing a sub-area to explore, plus a fifth row for any cross-cutting theme.
3. **Search depth** — let the requester choose, and say what constrains it.
| Depth | Searches | Allocation |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| Quick scan | 5 | 5 sub-area searches; skip era-gated and review-specific passes |
| **Standard** (recommended) | 10 | 5 sub-area · 2 review-article · 2 era-gated · 1 follow-up on the highest-cited paper |
| Deep dive | 20 | 5 sub-area · 5 review-article · 4 era-gated · 3 follow-ups on top-cited papers · 3 spare for emerging threads |
The key idea: extra budget buys **deeper analysis**, not more of the same. Review-article searches (`systematic review [topic]`, `meta-analysis [topic]`) are disproportionately valuable because one good review pre-digests dozens of primary studies.
## Phase 4 — Execute
Run searches **sequentially** — send, wait for the result, confirm it contains data, record what came back, then send the next. There is a one-query-per-second limit on every plan except Enterprise, so parallel firing produces 429s rather than speed. See [rate limits](/use-cases/best-practices#rate-limits-and-result-caps).
**Era-gated searches** are the cheapest way to understand a field's trajectory: run the most important sub-area once with `year_max: 2015` and once with `year_min: 2021`, then compare.
* **Terminology shifts** — "gut flora" became "gut microbiome". A researcher searching only modern terms will miss foundational older work.
* **Conclusion shifts** — older papers reaching different conclusions signals a paradigm shift or accumulating evidence.
* **Methodological evolution** — observational studies → RCTs → meta-analyses tells you how mature the evidence base is.
### Cross-search intelligence
This is what turns a pile of results into field knowledge. Track three things across **all** searches:
1. **Repeat-hit papers.** A paper appearing in 3 of 5 sub-area searches is foundational to the whole field, not just one sub-area. Flag these as must-reads.
2. **Recurring authors.** The same author group across multiple searches signals a dominant lab. Note the top 3–5 — anyone entering this field needs to know the key voices.
3. **Citations per year.** Divide citation count by years since publication. A 2023 paper with 150 citations is a far stronger signal than a 2008 paper with 150.
## Phase 5 — Produce the guide
Structure the output as a launch pad:
1. **Topic overview** — one tight paragraph: what the topic is, which framework was used, and a characterization of the evidence landscape ("robust on X, sparse on Y").
2. **Start here — priority reading order.** The most actionable section. 5–7 papers across all sub-areas, ordered as a newcomer should read them: best recent review first, then the foundational paper(s), then 2–3 at the current frontier, ending with one that highlights a gap or controversy. Per paper give what it contributes *in the sequence* and what to pay attention to while reading it ("focus on Table 3, which compares effect sizes across all RCTs").
3. **How the field got here** — a 5–8 row timeline plus a note on terminology evolution.
4. **Sub-area guides** — per sub-area: what the research shows, 3–5 key papers, 6–10 search terms including historical ones, and 2–3 ready-to-paste Boolean strings.
5. **Key research groups** — the 3–5 most frequent authors, their sub-areas, a representative paper each.
6. **Open questions and gaps** — split into methodological, population/context, and conceptual. For each, say *why it matters*, not just that it is unstudied.
7. **Bibliography** — alphabetical, every entry with a clickable full Consensus URL.
8. **Audit log.**
## Audit requirements
Follow the [grounding rules](/use-cases/best-practices#grounding-and-auditability). For this workflow, log per search: query, filters as sent, papers returned, status. Then report searches executed, searches successful, searches failed after retry, unique papers received after dedup, and papers cited.
State the detected plan cap and what it means for coverage: at 10 successful searches with a 10-result cap, the theoretical ceiling is 100 papers before dedup. Flag any sub-area returning fewer than 5 papers as potentially incomplete coverage rather than a genuine gap.
## What to check before you trust it
* **Confirm the reading order is actually ordered.** If it is just five good papers with no sequencing logic, the most valuable section has degraded into a list.
* **Check the terminology note.** A field whose vocabulary shifted and whose guide does not mention it will send researchers into incomplete searches.
* **Watch for silent filter emptiness.** If a narrow pass returned almost nothing, relax one filter at a time and say which was binding — never present that as "little evidence exists".
* **Calibrate once.** Have a person check one sub-area's papers by hand before trusting the method at volume.
## Related
The teaching-focused sibling of this workflow.
Take the same method and run it unattended on a cron.
Rate limits, grounding rules, and the five primitives.
Browse the gallery by persona.
# Compare candidate materials against published test data
Source: https://docs.consensus.app/use-cases/materials-comparison
Search published performance data for each candidate under your actual operating conditions, and find out which combinations nobody has tested.
## What you get
A comparison matrix of candidates against the conditions you care about. Every populated cell cites a paper and the conditions the value was measured under. Every empty cell is a gap — and those are where your test budget should go.
## Who it's for
Materials, process, and reliability engineers choosing between options with incomplete internal data. Semiconductor, automotive, aerospace, and consumer-product R\&D groups.
## The move that makes this work
Express the requirement as **conditions**, not as a material name. The spec becomes the query: temperature range, cycle count, atmosphere, dimension, contaminant, load. Then hold those conditions constant across every candidate so the results are comparable.
A search for a material name returns everything ever written about it. A search for the material under your conditions returns the handful of papers that answer your question.
## How it works
Write the operating envelope out explicitly before searching. This is the step that determines whether the output is usable.
Run a query set per material or process, varying only the candidate. Anything else and you are comparing searches, not materials.
Without `domain=mat,eng,phys,chem`, technical vocabulary pulls in unrelated biomedical literature. This single parameter is the difference between a usable and an unusable result set.
Use `include_full_text_chunks=true`. A performance number without its test conditions is not comparable to another number, and conditions live in methods sections rather than abstracts.
Say plainly which candidate-condition combinations have no published data. That is the most actionable output of the whole exercise.
## The API call
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=copper hybrid bonding void formation thermal cycling reliability" \
--data-urlencode "domain=mat,eng,phys" \
--data-urlencode "include_full_text_chunks=true" \
--data-urlencode "page_size=50"
```
Full-text excerpts require a paid plan or an Enterprise API key and currently cover open-access papers. Engineering and materials literature skews toward closed-access conference proceedings, so expect coverage here to be patchier than in biomedicine — check before treating the matrix as complete.
Useful `domain` codes for this work: `mat` (materials), `eng` (engineering), `phys` (physics), `chem` (chemistry), `env` (environmental).
## What to check before you trust it
* **Verify conditions on every extracted value.** A modulus measured at room temperature says nothing about behaviour at 200°C, and the two look identical in a table.
* **Watch for standards mismatch.** Values measured under different test standards are not comparable even when units match.
* **Empty cells may be a terminology problem.** Before reporting a gap, re-run with the alternative names the field uses for the same material or process.
* **Published performance is best-case.** Laboratory conditions and production conditions differ; treat literature values as an upper bound to validate, not a spec to adopt.
## Related
Once you have chosen the material, find the conditions to run it at.
The extraction discipline this depends on.
Excerpt-first extraction and the rest of the primitives.
Browse the gallery by persona.
# Answer one question with many parallel searches
Source: https://docs.consensus.app/use-cases/parallel-search-angles
Decompose a research question into multiple search angles, gather evidence across all of them, and distill one cited answer.
## What you get
The retrieval pattern behind a good "ask a research question" feature: one user question becomes many angles, each angle its own search, and the results merge into a single summary the user can trace back to papers.
## Who it's for
Product engineers building research answers into an application — the difference between this and a single search is the difference between a demo and a product.
## How Phylo runs it
[Phylo](https://consensus.app/home/community-voices/phylo/)'s agents make parallel calls across multiple angles of a question, gather the relevant papers, and distill the results into a summary for the user. The workflow starts wherever the researcher is:
| Step | What happens |
| ---- | ----------------------------------------------------------------------------- |
| 1 | A biology question is defined — a hypothesis, a GWAS hit, or a dataset signal |
| 2 | The agent generates multiple search angles for better coverage |
| 3 | Consensus returns evidence across those retrieval paths |
| 4 | The agent distills it into a usable research answer |
> "It's very robust, with almost zero errors. It gives you genuinely useful results, and it embeds into a high-throughput agentic workflow easily."
>
> — **Kexin Huang**, Co-founder & CEO, Phylo
## Generating good angles
This is where the quality lives. A weak decomposition produces five rephrasings of the same query; a strong one covers genuinely different retrieval paths.
Cover the mechanism, the population, the outcome, the competing explanation, and the methodology. Five paraphrases of one angle retrieve nearly the same papers and give false confidence in coverage.
Add an angle phrased toward the opposite finding. Searching only for confirmation returns confirmation, and users notice when your product never disagrees with them.
The user's phrasing is rarely what the literature indexes under. Translate first — a reconnaissance search to learn the vocabulary, then the real angles.
"Parallel" here means angles, not simultaneous calls: there is a one-query-per-second limit on every plan except Enterprise, so issue the searches sequentially. See [rate limits](/use-cases/best-practices#rate-limits-and-result-caps).
A paper surfaced by several independent angles is a stronger signal than one found by a single query — that count is worth surfacing in the answer.
## Distilling without losing the thread
The synthesis step is where grounding usually breaks:
* **Group by finding, not by paper.** A paper-by-paper summary is a reading list; grouping by finding with the supporting papers attached is an answer.
* **Attach a citation to every claim** and drop sentences you cannot support. Make "the literature does not settle this" a real output.
* **Show which angles were searched.** It tells the user what was and was not covered, and it is the cheapest trust-building thing you can render.
* **Report disagreement.** Where angles returned conflicting evidence, say so rather than averaging it into a confident middle.
## What to check before you trust it
* **Inspect the generated angles on real questions.** If they are paraphrases, fix the decomposition prompt — no amount of retrieval quality compensates.
* **Test a question with a genuinely contested answer.** The output should surface the conflict, not resolve it silently.
* **Watch merge behaviour on near-duplicates.** Preprint and published versions of the same work can carry different DOIs.
* **Measure it.** Use a [benchmark](/use-cases/benchmark-retrieval) to check whether more angles actually improve recall, or just cost more.
## Related
The batch counterpart, on the same infrastructure.
Wiring this into an agent you have already built.
Fan-out and merge, rate limits, and the five primitives.
Browse the gallery by persona.
# Assemble a payer evidence dossier
Source: https://docs.consensus.app/use-cases/payer-evidence-dossier
Pull the cost-effectiveness, burden-of-illness, and real-world evidence a reimbursement submission needs, in one pass.
## What you get
A structured evidence pack spanning four literatures that rarely sit together: clinical efficacy, burden of illness, economic evaluation, and real-world outcomes — each section cited, with the gaps named.
## Who it's for
HEOR and market access teams building reimbursement submissions, and the consultancies who build them on their behalf.
## Why this one is awkward
Payer dossiers span clinical and economic literature that use different vocabularies, sit in different journals, and are indexed under different fields. A single query returns one of them and misses the rest. The fix is running four deliberately separate searches and keeping them separate in the output.
## The four searches
| Section | What you are looking for | Filters that help |
| ----------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
| **Clinical efficacy** | Trials and meta-analyses establishing the effect | `study_types=rct,meta-analysis`, `human=true` |
| **Burden of illness** | Prevalence, mortality, quality of life, productivity loss | `domain=med,econ`, `study_types=cohort study,cross-sectional study` |
| **Economic evaluation** | Cost-effectiveness, cost-utility, budget impact | `domain=econ,med` |
| **Real-world evidence** | Registry, claims, and observational outcomes outside trials | `study_types=cohort study,longitudinal / panel data study` |
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=cost-effectiveness analysis quality-adjusted life year heart failure treatment" \
--data-urlencode "domain=econ,med" \
--data-urlencode "human=true" \
--data-urlencode "page_size=50"
```
Add `country` when the submission is to a specific national payer — cost-effectiveness evidence is jurisdiction-dependent, and a US cost-per-QALY carries little weight with a European HTA body.
## The prompt
```text theme={null}
You are assembling the evidence base for a reimbursement dossier. Report each
section separately; do not merge them into a single narrative.
Product: [NAME] Indication: [INDICATION] Payer / jurisdiction: [MARKET]
1. Clinical efficacy — the effect, its size, its certainty, in whom.
2. Burden of illness — prevalence, mortality, quality of life, and economic
burden in the target jurisdiction where available. If the evidence is from
another country, say which and flag the transfer as an assumption.
3. Economic evaluation — published cost-effectiveness work, with the model type,
perspective, time horizon, and threshold used. Note when a study's
jurisdiction, currency, or year makes it non-comparable.
4. Real-world evidence — outcomes outside trial conditions, and how they differ
from trial results.
Then:
- Where the four sections disagree, and the most likely reason.
- Evidence gaps a payer is likely to challenge, stated plainly.
- What additional evidence would most strengthen the submission.
Cite everything with journal, year, and DOI.
```
## Audit requirements
Follow the [grounding rules](/use-cases/best-practices#grounding-and-auditability). Log the four search sets separately with their counts. If a section returned little — economic evaluations are frequently sparse for newer products — that sparsity is a finding a payer will also notice, so report it rather than padding.
## What to check before you trust it
A literature pack is an input to a submission, not a submission. HTA requirements are jurisdiction-specific and prescriptive; the dossier's structure and evidence standards come from the payer's own guidance, not from this workflow.
* **Check jurisdiction on every economic study.** Cost-effectiveness does not transfer across health systems, and a reviewer will spot a mismatched threshold immediately.
* **Check currency and year.** Costs from a decade ago in another currency need conversion and inflation adjustment before they mean anything.
* **Read the gap section first.** Where the evidence is thin is exactly where the payer will push, so it is the most useful output.
* **Real-world and trial evidence disagreeing is normal.** Explain the gap rather than presenting only the flattering one.
## Related
Keep watching the evidence base after submission.
Score the evidence you assemble consistently.
Fan-out and merge, and the rest of the primitives.
Browse the gallery by persona.
# Build a PRISMA-ready search corpus
Source: https://docs.consensus.app/use-cases/prisma-corpus
Assemble a reproducible, deduplicated record set with the flow counts a systematic review has to report.
## What you get
A deduplicated corpus, a search strategy locked before results were seen, and the counts PRISMA asks for: records identified, duplicates removed, records screened, records excluded with reasons.
This is a recipe built on the API, not a packaged product. Consensus supplies the search, filters, and pagination; you own the strategy log and the flow diagram. It is one of the most requested workflows we do not yet ship end to end.
## Who it's for
Methodologists and research-software teams producing a corpus that has to survive peer review, plus anyone publishing where PRISMA reporting is mandatory.
## Lock the strategy first
Reproducibility is decided before you search, not after. Write down and persist:
* the full query list
* every filter, exactly as it will be sent
* the inclusion and exclusion criteria
* the date the search was run
A strategy adjusted after seeing results is a search, not a method. If you must change it, version it and report both.
## Sweep to exhaustion
```python theme={null}
import os, requests
API = "https://api.consensus.app/v1/search"
HEADERS = {"x-api-key": os.environ["CONSENSUS_API_KEY"]}
STRATEGY = dict(
study_types=["rct", "meta-analysis", "systematic review"],
human=True, year_min=2015, exclude_preprints=True, page_size=200,
)
def sweep(query):
page, out = 0, []
while page <= 49: # 0-indexed; 49 is the ceiling
r = requests.get(API, headers=HEADERS, params={"query": query, "page": page, **STRATEGY})
r.raise_for_status()
body = r.json()
out.extend(body["results"])
if body["is_end"] or body.get("next_page") is None:
break
page = body["next_page"]
return out
corpus, per_query = {}, {}
for query in QUERY_SET: # your locked list
found = sweep(query)
per_query[query] = len(found) # pre-dedup count, needed for PRISMA
for paper in found:
corpus.setdefault(paper["doi"], paper)
```
Pagination and page sizes above 20 need a paid plan or Enterprise key; `page_size` caps at 300 (Pro, Teams), 750 (Deep), higher on Enterprise. Over-large requests are clamped, not rejected — read the `page_size` echoed back. See [rate limits](/use-cases/best-practices#rate-limits-and-result-caps).
## Deduplicate and count
Merge on `doi`, keeping the first-seen record plus which queries found it. Retain **both** the pre- and post-deduplication totals — PRISMA reports each separately, and you cannot reconstruct them later.
Records without a DOI need a fallback key (normalized title plus year). Count how many took that path; a large number signals a coverage or record-quality problem worth mentioning.
## What PRISMA wants back
| Flow stage | Where it comes from |
| ------------------------------ | ----------------------------------------------------------------------- |
| Records identified | Sum of per-query pre-dedup counts |
| Duplicates removed | Pre-dedup total minus unique DOIs |
| Records screened | Size of the deduplicated corpus |
| Records excluded, with reasons | From [abstract screening](/use-cases/abstract-screening), per criterion |
| Full-text assessed | Records escalated past abstract screening |
| Studies included | Final set |
Consensus is one source. A review claiming comprehensive coverage will normally be expected to search additional databases and registries, and reviewers will ask which ones. Report Consensus as one search source with its date and strategy, not as the whole search.
## Audit requirements
Follow the [grounding rules](/use-cases/best-practices#grounding-and-auditability). Persist per query: the query text, filters exactly as sent, pages walked, records returned, and the run date. That table *is* your methods section's evidence.
## What to check before you trust it
* **Confirm you actually reached the end.** A sweep that stopped at page 49 with `is_end` false has truncated results — say so, or narrow the query and re-run.
* **Check the dedup key.** Preprint and published versions of the same study carry different DOIs and will both survive.
* **Re-run the strategy on the reporting date.** Literature moves; reviewers expect a search date, and a stale corpus invites a "please update" revision.
## Related
The next step, with the exclusion reasons PRISMA needs.
Turn the strategy log into publishable prose.
Exhaustive sweep, rate limits, and the five primitives.
Browse the gallery by persona.
# Find published process conditions for a manufacturing step
Source: https://docs.consensus.app/use-cases/process-window-precedent
See what temperature, time, atmosphere, and concentration ranges others have published for a process, so you start from precedent rather than from scratch.
## What you get
A table of published process conditions for your step — each with the material system it applied to, the outcome achieved, and the paper it came from. A starting envelope for your own DOE instead of a blank one.
## Who it's for
Process engineers standing up a new process, transferring one between sites or tools, or trying to widen a window that keeps drifting out of spec.
## Why this needs full text
Process conditions live in methods sections. Abstracts report that a process worked; they almost never report the temperature ramp, the dwell, the atmosphere, or the concentration. This use case depends on `include_full_text_chunks=true` and on phrasing the query as the conditions themselves.
Full-text excerpts require a paid plan or an Enterprise API key and currently cover open-access papers. Process literature is heavily represented in closed conference proceedings, so expect partial coverage and treat what you get as a starting point rather than a survey.
## The extraction schema
Fix these columns before you start, or you will end up with values you cannot compare:
| Column | Why |
| --------------------- | ---------------------------------------------------- |
| Process step | The specific operation, not the overall flow |
| Parameter and value | With units exactly as published |
| Range or single point | A window is far more useful than one setting |
| Material system | Conditions rarely transfer across substrates |
| Tool or method | Equipment differences change achievable ranges |
| Outcome achieved | The condition means nothing without what it produced |
| Source | DOI plus the excerpt the value came from |
## The API call
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=atomic layer deposition alumina process temperature precursor pulse time conditions" \
--data-urlencode "domain=mat,eng,chem" \
--data-urlencode "include_full_text_chunks=true" \
--data-urlencode "page_size=100"
```
Phrase the query as the parameter you want, not the process in general — excerpts are selected for relevance to your query, so `deposition temperature precursor pulse` returns methods paragraphs while the bare process name returns introductions.
## What to check before you trust it
* **Never transfer conditions without checking the material system and tool.** Published conditions are specific to a substrate, a reactor geometry, and a precursor. They are a starting point for a DOE, not a recipe.
* **Watch for missing parameters.** Papers routinely omit one condition that turns out to be load-bearing. Mark those as NOT REPORTED rather than assuming a standard value.
* **Prefer papers reporting a window over a single point.** A range tells you the sensitivity; a point tells you almost nothing about robustness.
* **Check the outcome definition.** "Successful deposition" means different things across groups; align on the metric before comparing conditions.
## Related
The general extraction discipline underneath this.
When the process window keeps producing defects.
Excerpt-first extraction and the rest of the primitives.
Browse the gallery by persona.
# Track new papers across many topics on a schedule
Source: https://docs.consensus.app/use-cases/scheduled-research-pipeline
Sweep hundreds of topics on a cron, diff against the last run, and report only what changed.
## What you get
An unattended job that re-runs a fixed query set on a schedule, stores what it has seen, and produces a delta — the papers that are new since last time, ranked by whether they change a decision you have already made.
One research team runs this across 121 countries every six hours to track education-reform literature, feeding a public site. The shape generalizes to any entity list: compounds, competitors, materials, indications, regions.
## Who it's for
Engineers and technical researchers maintaining a living evidence base rather than answering a one-off question. Runs from Codex, Claude Code, a GitHub Action, or any scheduler.
## How it works
Separate the two. One template — "education reform outcomes in " — crossed with an entity list is far easier to maintain and audit than hundreds of hand-written queries.
Set `year_min` and `month_min` to the last successful run rather than filtering client-side. You retrieve less, pay for less, and get a cleaner set.
Walk `page` from `0` while `is_end` is false. Pagination runs to page 49 and `page_size` caps at your plan's maximum, so one query can reach tens of thousands of records.
Persist every DOI you have reported. The run's output is the set difference, not the search results.
A run that finds nothing is a record you need — it distinguishes "no new evidence" from "the job silently broke three weeks ago."
## The pipeline
```python theme={null}
import os, time, requests
API = "https://api.consensus.app/v1/search"
HEADERS = {"x-api-key": os.environ["CONSENSUS_API_KEY"]}
STRATEGY = dict(
study_types=["rct", "meta-analysis", "systematic review"],
exclude_preprints=False, # early signals often appear as preprints first
page_size=200,
)
def sweep(query, since):
"""Every record for one query since the last run."""
page, out = 0, []
while page <= 49: # 0-indexed; 49 is the ceiling
resp = requests.get(API, headers=HEADERS, params={
"query": query,
"year_min": since.year,
"month_min": since.month,
"page": page,
**STRATEGY,
})
if resp.status_code == 429: # rate limited — back off and retry
time.sleep(int(resp.headers.get("retry-after", 30)))
continue
resp.raise_for_status()
body = resp.json()
out.extend(body["results"])
if body["is_end"] or body.get("next_page") is None:
break
page = body["next_page"]
return out
def run(entities, template, since, seen_dois):
new, counts = {}, {}
for entity in entities:
results = sweep(template.format(entity=entity), since)
counts[entity] = len(results)
for paper in results:
doi = paper.get("doi")
if doi and doi not in seen_dois:
new[doi] = {**paper, "entity": entity}
return new, counts # persist counts even when new is empty
```
Pagination and page sizes above the default of 20 require a paid plan or an Enterprise API key. `page_size` caps at 300 on Pro and Teams, 750 on Deep, and higher on Enterprise keys. A request over your ceiling is clamped rather than rejected — read the `page_size` echoed back in the response.
## Rate limits and backoff
Build backoff in before you widen the entity list, not after.
* **Pace to one search per second.** That is the limit on every plan except Enterprise, so build the pacing into the pipeline rather than firing entities in parallel. Honour `retry-after` and add jitter between entities.
* A **429 mentioning your monthly search allowance** is a usage limit, not a rate limit — retrying will not help. Turn on additional usage in your account settings to keep searching past the included allowance.
* Scheduled runs consume searches like any other request. A 121-entity sweep every six hours is roughly 484 entity-sweeps a day before pagination; size your plan for it.
## Reporting the delta
Rank the new papers by whether they change a decision, not by citation count — a paper published this week has none yet. A useful report is five items with one line each and a link, plus an explicit "nothing notable this run" state that actually gets used.
## What to check before you trust it
* **Alert on the job, not just the findings.** A silent pipeline looks identical to a quiet literature. Persist per-run counts and alert when a run returns zero results across *all* entities.
* **Version the query template.** When you change it, the delta becomes incomparable to previous runs. Record the template version alongside each run.
* **Watch for entity-name collisions.** Short or ambiguous entity names pull in unrelated work. Spot-check the highest-volume entities.
* **Cache if you re-query.** Heavy users hit this fast; cache on the full parameter set with a short TTL.
## Related
The same machinery, pointed at a commercial watchlist.
The interactive version of the same method.
Exhaustive sweep and diff-against-last-run in detail.
Browse the gallery by persona.
# Write the search-strategy section of your methods
Source: https://docs.consensus.app/use-cases/search-strategy-methods
Turn a logged search into the reproducible methods paragraph reviewers ask for — accurate because it was recorded as it ran.
## What you get
The paragraph that says exactly what you searched, with which filters, on what date, returning how many records — written from a log rather than reconstructed from memory weeks later.
## Who it's for
Anyone publishing a review, meta-analysis, or scoping study. Also anyone who has been asked by a reviewer to "provide the full search strategy" and discovered they cannot.
## Why this is worth automating
Search strategies are almost always written last, from half-remembered queries, after the interesting work is done. The result is a paragraph that does not reproduce the corpus it claims to describe — which reviewers increasingly check.
If the agent logs each call as it runs, this section costs nothing and is actually true.
## What to log, as you go
| Field | Why a reviewer wants it |
| ----------------------------- | ----------------------------------------------------------------------- |
| Query text, verbatim | The only way anyone reproduces your set |
| Every filter, exactly as sent | `study_types`, `human`, `year_min`, `sjr_max` all change the result set |
| Date the search ran | Literature moves; a search has an as-of date |
| Records returned per query | Pre-deduplication totals for the flow diagram |
| Records after deduplication | Reported separately from the above |
| Pages walked | Shows whether you exhausted the result set or took page one |
| Any failed or retried call | A gap in coverage you must disclose |
## The prompt
```text theme={null}
You are writing the search-strategy subsection of a methods section from the
log below. Write prose, not a table — journals want a reproducible narrative.
Cover, in this order:
1. The source searched, named precisely, with the date the search was run.
2. The query set. Give the queries verbatim; do not paraphrase them.
3. Every filter applied, with the value used and one clause on why. A filter
with no stated rationale reads as arbitrary.
4. How records were deduplicated and on what key.
5. The counts: records identified, duplicates removed, records screened.
6. Any limitation: failed searches, truncated result sets, plan-imposed caps
on returned results, or coverage restricted to a subset of the literature.
Rules:
- Use only the log. If a field is missing, write [NOT RECORDED] rather than
reconstructing it — an invented search strategy is worse than an incomplete one.
- Do not describe the search as comprehensive or exhaustive unless the log
shows every query was paginated to completion.
- State plainly that this was one search source and name any others used
separately.
Log:
[PASTE THE AUDIT LOG]
```
## Getting the filter rationale right
Reviewers reject filters that look like convenience. Each one needs a defensible reason:
* `study_types` — the designs that can answer the question, not the ones that returned pleasing results
* `human=true` — scope of the review, stated in the question
* `year_min` — tie it to an event, a guideline change, or a method's introduction, not to a round number
* `sjr_max` — quality thresholds are contestable; say why the cut is where it is
* `exclude_preprints` — a real methodological choice with a cost either way; justify the direction
## Audit requirements
This use case *is* the audit log, rendered as prose. Follow the [grounding rules](/use-cases/best-practices#grounding-and-auditability), and keep the machine-readable table as a supplement — many journals now accept it as an appendix, which is stronger than the paragraph alone.
## What to check before you trust it
* **Reproduce your own corpus from the paragraph.** If you cannot, a reviewer cannot either, and that is the entire test.
* **Check for `[NOT RECORDED]`.** Each one is a real gap. Fill it by re-running, not by remembering.
* **Do not claim comprehensiveness you did not achieve.** A truncated sweep described as exhaustive is a correctable error before submission and a serious one after.
## Related
The sweep that generates this log.
Where the exclusion reasons come from.
Grounding rules and the audit-log format.
Browse the gallery by persona.
# Check a supplier's performance claim against independent research
Source: https://docs.consensus.app/use-cases/supplier-claim-check
Test what a vendor says their material, tool, or process achieves against what the published literature independently reports.
## What you get
A per-claim verdict on a supplier's technical assertions: independently supported, supported only under narrower conditions, contradicted, or unstudied — with citations and the specific conditions each finding applies to.
## Who it's for
Technical evaluation teams, process and materials engineers assessing a new supplier, and anyone whose qualification programme is about to be sized around a vendor's datasheet.
## How it works
"Higher throughput and better uniformity" is two claims with different evidence. Extract each as a proposition naming the material or system, the condition, the metric, and the comparator.
"30% better" is meaningless without what it is better than. If the vendor has not said, that is itself a finding — record it and search against the conventional alternative.
Trade names rarely appear in the literature. Search the underlying material, chemistry, or technique. This is the step that determines whether you find anything at all.
Search explicitly for null findings and failures with this approach. Independent groups publish disappointments that vendors do not mention.
A claim independently confirmed under conditions unlike your process is not confirmed for you. State the delta.
## The API calls
```bash theme={null}
# independent evidence for the mechanism
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=graphene-enhanced thermal interface material conductivity measured performance" \
--data-urlencode "domain=mat,eng,phys" \
--data-urlencode "include_full_text_chunks=true" \
--data-urlencode "page_size=50"
# negative pass
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=graphene thermal interface material no improvement limitations contact resistance" \
--data-urlencode "domain=mat,eng,phys" \
--data-urlencode "page_size=50"
```
## Grading each claim
| Verdict | Meaning |
| --------------------------- | --------------------------------------------------------------------------------- |
| **Independently supported** | Multiple independent groups report comparable results under comparable conditions |
| **Supported, narrower** | Confirmed, but only under conditions narrower than claimed. State which |
| **Vendor-only** | The only supporting work is authored or funded by the supplier |
| **Contradicted** | Independent work reports the opposite or finds no effect |
| **Unstudied** | No independent literature. Not the same as false — say what you searched |
The **vendor-only** row does most of the work here. A claim supported exclusively by the supplier's own publications is not independently verified, and that distinction rarely survives a datasheet review otherwise.
## What to check before you trust it
* **Check author affiliations on supporting papers.** Supplier-authored or supplier-funded work is legitimate evidence but is not independent, and the difference matters for a qualification decision.
* **Unstudied is not disproven.** A genuinely novel material will have thin independent literature. Treat it as a reason to test rather than a reason to reject.
* **Coverage is patchy in this literature.** Much applied engineering work sits in closed proceedings; a thin result is weak evidence of absence.
* **This informs qualification, it does not replace it.** The literature tells you what to test and what to watch for, not whether the part works in your process.
## Related
Evaluate the alternatives on the same footing.
The same discipline applied to your own claims.
Filter ladder and the rest of the primitives.
Browse the gallery by persona.
# Swap a hand-maintained paper corpus for full-text search
Source: https://docs.consensus.app/use-cases/swap-a-paper-corpus
Replace a curated PubMed subset you maintain yourself with a weekly-refreshed full-text index, without rebuilding the infrastructure.
## What you get
Your agents stop reasoning over a stale slice of abstracts and start reasoning over full-text findings, with quality filters and a link back to every source. And nobody on your team maintains a corpus pipeline any more.
## Who it's for
Engineers who own "the literature service" at an AI-for-science company — the one who inherited a scraped or licensed PubMed subset and now owns its refresh, its gaps, and its quality problems.
## What it replaced at Owkin
[Owkin](https://consensus.app/home/community-voices/owkin/) builds AI tools for biopharma drug discovery. Its flagship product, K Pro, is an Agentic AI Scientist orchestrating specialized agents across clinical trial design, patient and population decisions, and early portfolio choices.
Early versions of K Pro ran on a curated collection of PubMed abstracts. Serviceable, but it left agents reasoning from titles and summaries rather than full-text findings, with limited filtering for study quality and no built-in defense against hallucination.
> "We went from maintaining a collection of PubMed abstracts to 200M+ full-text articles updated weekly, with hallucination safeguards built in. It's exactly the kind of best-in-class building block we want to compose with, rather than rebuild."
>
> — **Lucas Brechot**, Senior Product Manager, AI Products, Owkin
| | Result |
| -------------- | ---------------------------------------------------- |
| Paper coverage | **25x** increase |
| Index refresh | **Weekly** |
| Time to ship | **Days**, against weeks or months of custom building |
## Why abstracts are the wrong foundation
Effect sizes, conditions, populations, and limitations live in the body of a paper. An agent restricted to abstracts produces answers that are confident and shallow — the worst combination in a high-stakes domain.
Someone has to keep it fresh, handle schema drift, and explain the gaps. That work is invisible until it breaks, and it is never the thing your product is differentiated on.
Human researchers instinctively weigh recency, citation count, and journal reputation. Agents need those as parameters — `year_min`, `citation_min`, `sjr_max` — or they treat a 1998 case report and a 2025 meta-analysis as equivalent.
Every result carries a `doi` and a `url` back to the paper. That is what turns "the model says" into "this paper says", which is the difference that matters to your users.
## Making the swap
Point your retrieval layer at the [MCP server](/consensus-mcp) or [`GET /v1/search`](/api-get-started), and map your existing corpus filters onto the parameters that replace them:
| What you maintained | What replaces it |
| --------------------------------------- | ------------------------------------------- |
| A recency cutoff on your ingest | `year_min`, `month_min` |
| A journal allowlist | `sjr_max`, `journal_name`, `publisher_name` |
| A study-design tag you derived yourself | `study_types`, `human`, `controlled` |
| A minimum-quality heuristic | `citation_min`, `sample_size_min` |
| Your own full-text extraction | `include_full_text_chunks` |
| A domain restriction | `domain`, `medical_mode` |
`include_full_text_chunks` requires a paid plan or an Enterprise API key and currently covers open-access papers. Pagination has the same plan gating — see [rate limits](/use-cases/best-practices#rate-limits-and-result-caps).
## What to check before you trust it
* **Run your old corpus and the new one side by side** on the same queries before cutting over. You are looking for regressions on your niche, not average quality.
* **Check the filters actually narrow the way your old pipeline did.** A corpus restriction you enforced at ingest becomes a per-request parameter, and it is easy to forget one.
* **Confirm coverage on your specific subfield.** Full-text excerpts currently cover open-access papers, so a closed-access niche will look thinner than it is.
* **Keep the DOI.** If your product cites papers, the `doi` and `url` are what make the citation checkable downstream.
## Related
The same integration, framed as an addition rather than a replacement.
How to decide whether the swap is actually an upgrade.
Rate limits, grounding rules, and the five primitives.
Browse the gallery by persona.
# Turn a syllabus into a recommended reading list
Source: https://docs.consensus.app/use-cases/syllabus-reading-list
Extract course topics and learning outcomes from a syllabus, then produce a curated reading list of recent research with summaries and discussion questions.
## What you get
A ready-to-distribute reading list: 15–25 recent peer-reviewed papers grouped under your course's own topic sections, each with a clickable link, a plain-language summary written for students, and a discussion question tied to a stated learning outcome. Plus an audit log showing exactly which searches produced it.
Consensus ships this as a packaged skill. The workflow below is what it does, so you can run it as-is, adapt it, or build it into your own tooling.
## Who it's for
Faculty refreshing a course, curriculum designers, and corporate training teams who need current research rather than last year's list.
## Before anything else: check the tool is attached
The workflow is gated on Consensus actually being callable — not installed, not authorized elsewhere, but present in this conversation. Verify before parsing the syllabus, and if it is missing, stop and ask the user to attach it with the **+** button or by tagging `@Consensus`. Do not fall back to web search or model knowledge for paper discovery; the whole point is verifiable citations.
## Phase 1 — Parse the syllabus
Extract two things from the uploaded file (PDF, DOCX, image, or pasted text):
1. **Course topics** — the ordered list of units. These become the reading list's sections.
2. **Learning outcomes** — the course-level goals. These drive the discussion questions.
If the syllabus states no explicit outcomes, infer 3–5 from the course description and topic list.
Group closely related topics — "Protein Structure" and "Protein Function" become one section. Aim for **6–12 sections**: enough granularity to be useful, not so many that the document fragments. Present the grouping and confirm it before searching.
## Phase 2 — Search per section
Write the full query plan first and record its total count. The phase is complete only when every planned query has produced an actual response and appears in the audit log. A zero-result response counts as complete; an intended call does not.
**Query design is where this workflow succeeds or fails:**
* Include the core topic **plus an applied angle**. For a biochemistry course with a nutrition focus, don't search `enzyme kinetics` — search `enzyme kinetics food processing applications`.
* If the course has an obvious applied domain, weave it into *every* query. That is what surfaces papers bridging theory and application, which make far better supplementary reading than narrow primary research.
* Keep queries to **4–8 words**. Longer queries dilute relevance.
| Section | Query |
| ---------------------------- | ---------------------------------------------------- |
| Nucleic Acids | `nucleic acid structure function food safety` |
| Amino Acids | `amino acid nutrition metabolism health` |
| Enzyme Function & Kinetics | `enzyme kinetics food processing applications` |
| Lipids & Membranes | `lipids biological membranes lipoproteins nutrition` |
| Energy Metabolism in Disease | `energy metabolism diabetes insulin resistance` |
Set `year_min` to the current year minus one by default. Run searches **sequentially** — send, wait, confirm, then send the next. See [rate limits](/use-cases/best-practices#rate-limits-and-result-caps) for the per-tier ceiling.
**Selection criteria, in priority order:**
1. Relevance to the course topic
2. Reviews and meta-analyses over narrow primary research — they give students a broader entry point
3. Higher citation counts
4. Clear connection to the course's applied domain
Select **1–3 papers per section**, targeting 15–25 total.
## Phase 3 — Write summaries and questions
Base every summary only on what the search returned — title, abstract, metadata. If a result lacks enough context for a meaningful summary, say so rather than inventing detail.
**One-sentence summary**, written for undergraduates. Define technical terms in parentheses; the summary should make a student want to read the paper.
> **Good:** "This review maps how different diets — Mediterranean, Nordic, and vegetarian — reshape the types of fat molecules circulating in your blood, with implications for heart disease risk."
>
> **Bad:** "This paper reviews lipidomic profiles across dietary interventions and their cardiometabolic implications." — too jargon-heavy for the audience.
**Discussion question** tying the paper to a learning outcome, pushing past recall into apply, analyze, or evaluate.
> **Good:** "If dietary fat quality can reshape your lipoprotein lipidome, what does this suggest about the biochemical basis for dietary guidelines recommending unsaturated over saturated fats?"
>
> **Bad:** "What did the authors find?" — pure recall.
## Phase 4 — Build the document
An editable Word document, not a PDF, so the instructor can cut sections into their own materials:
* Title block: course title, generation date, publication-year range
* A short introduction stating the readings came from Consensus results in this session
* A **Course Learning Outcomes** section
* Numbered papers under each confirmed topic heading
* Per paper: clickable title linked to its full Consensus URL, authors, journal, year, plain-language summary, discussion question
* A **Search Audit Log**
Render the finished document to page images and inspect every page for overflow, clipping, broken links, and orphaned headings before delivering.
## Audit requirements
Follow the [grounding rules](/use-cases/best-practices#grounding-and-auditability). For this workflow specifically, the audit log carries one row per section: section, query, filters as sent, papers found, papers returned, papers selected, status. Then the totals — queries sent, papers returned, papers cited — plus any detected plan cap and any failure.
Report the same numbers in your closing message, not just in the document:
> **Search summary:** Ran 12 queries across 10 sections. Consensus returned 34 papers. Selected 18 for the list. No failures.
>
> **Sections with limited results:** "Nitrogen Metabolism" returned only 1 relevant paper — worth supplementing manually.
## What to check before you trust it
* **Check for padding.** A section with three recommendations where the field published little is the failure mode. Sparse sections should be flagged, not filled.
* **Read the summaries as a student would.** If they read like abstracts, the audience instruction was ignored.
* **Verify the level.** Recent frontier papers are often unsuitable for an introductory course regardless of relevance.
* **Confirm access** before assigning anything students must read. Add `open_access=true` when students lack broad institutional access.
* **Non-English courses:** search in English since Consensus indexes English-language papers, and note the course language in the document.
## Related
The deeper research version, with framework selection and search budgets.
Another packaged skill built on the same search discipline.
Rate limits, grounding rules, and the five primitives.
Browse the gallery by persona.
# Build a drug target validation dossier
Source: https://docs.consensus.app/use-cases/target-evidence-tiers
Human genetics, in vitro, animal, and clinical evidence for one target in a single pass — including what contradicts it.
## What you get
A target dossier organized by evidence tier, with a strength grade per tier, an explicit disconfirming-evidence section, and a named next experiment. The ratio between preclinical and clinical volume is itself part of the finding.
## Who it's for
Discovery and translational teams deciding whether a target justifies a program, and reviewers pressure-testing that decision.
## The prompt
```text theme={null}
You are a translational biology researcher building a target validation dossier.
Target: [TARGET]
Indication: [INDICATION]
Search each evidence tier separately using Consensus. Report them separately —
do not merge tiers into a single narrative.
Tier 1 — Human genetics
Loss-of-function and gain-of-function variants, GWAS associations, Mendelian
randomization. Does human genetic variation in this target move the phenotype,
and in which direction?
Tier 2 — In vitro and mechanistic
Cell models, biochemical assays, pathway position. What does modulating the
target actually do, and in what system?
Tier 3 — Animal models
Knockout and knockdown phenotypes, pharmacological modulation, which species
and which model. Note where the model is a poor proxy for the human disease.
Tier 4 — Human observational
Expression, biomarker association, natural-history cohorts.
Tier 5 — Human interventional
Any trial of an agent hitting this target or its pathway, in this or any
indication. Include failures and terminations.
For every tier, report: the number of papers found, what they show, the
consistency of the direction of effect, and a strength grade of strong,
moderate, weak, or absent.
Then, as separate sections:
Disconfirming evidence — search explicitly for contradictory findings, failed
trials, non-replications, and negative results on this target. A dossier with
no disconfirming section has not been done. If you genuinely find none, say
what you searched.
Safety and tractability — knockout phenotype severity, expression in tissues
where modulation would be harmful, known adverse effects of agents hitting this
pathway.
Translational gap — state plainly whether human evidence exists or whether this
is preclinical only. Report the ratio of preclinical to clinical papers.
Finish with: the single experiment or dataset that would most reduce
uncertainty about this target.
Cite every claim with journal, year, and DOI.
```
## How it works
`study_types=animal` and `non-rct in vitro` isolate preclinical work; `human=true` with `rct` and `cohort study` isolates the clinical tier. Running both and comparing volumes gives you the translational gap for free.
Querying the target's name and indication returns confirmation. Finding the failures requires separate queries phrased toward failure — termination, non-replication, negative result.
Merging tiers lets a large volume of in vitro work stand in for absent human evidence. Grading each tier independently prevents that.
## The API equivalent
```bash theme={null}
# Tier 1 — human genetics
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=GPR75 obesity body mass index human genetic association loss of function" \
--data-urlencode "human=true" \
--data-urlencode "domain=med,bio" \
--data-urlencode "page_size=50"
# Tier 3 — animal models
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=GPR75 knockout mouse adiposity phenotype" \
--data-urlencode "study_types=animal" \
--data-urlencode "page_size=50"
# Disconfirming pass
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=GPR75 negative result failed replication no effect adiposity" \
--data-urlencode "page_size=50"
```
## What to check before you trust it
A literature dossier is an input to a target decision, not the decision. Keep the citation trail so a reviewer can check each tier's grade against its sources.
* **Check the disconfirming section is real.** If it is empty or generic, the negative queries were not run. That section failing is the difference between a dossier and a pitch.
* **Preclinical volume is not evidence strength.** Fifty in vitro papers and no human data is a weak target with a large literature. The ratio should be stated plainly.
* **Watch for pathway substitution.** Evidence for a pathway is often presented as evidence for a specific target. Check that Tier 1 and Tier 5 are about the target itself.
* **Gene-name synonyms matter.** Older aliases and gene-family names return different literature. Confirm the search covered them.
## Related
The same tiered discipline, applied to a biomarker range.
Keep watching the target once the program starts.
Fan-out, the filter ladder, and the rest of the primitives.
Browse the gallery by persona.
# Track how a field's terminology changed over time
Source: https://docs.consensus.app/use-cases/terminology-shift
Compare old and recent literature on the same concept so you search the terms the field actually used, not just the ones it uses now.
## What you get
A mapping of old vocabulary to current vocabulary for your topic, a note on when the shift happened, and a search-term list covering both — so a review does not silently miss its own foundational literature.
## Who it's for
Anyone entering an unfamiliar field, and every systematic reviewer, where missing older work is a methodological failure rather than an inconvenience.
## Why this matters more than it sounds
"Gut flora" became "gut microbiome". "Manic depression" became "bipolar disorder". "Mental retardation" became "intellectual disability". Search only the current term and the foundational decade of a literature is invisible to you — and nothing in your results indicates it is missing.
This is one of the few review failures that produces no error signal at all.
## How it works
One search with `year_max` set before the suspected shift, one with `year_min` set after. Same concept, deliberately different windows.
Pull the recurring noun phrases from titles and abstracts in each set. You are comparing how the field named the thing, not what it concluded.
Narrow the window year by year to locate when the new term overtook the old. That date is worth reporting — it tells later readers where your search boundary sits.
Terminology changes sometimes accompany a definitional change. "Gut flora" and "gut microbiome" are close to interchangeable; other renamings narrowed or widened what counts. Say which case applies.
Produce a single list with both vocabularies and an era note on each, ready to paste into any search.
## The API calls
```bash theme={null}
# older window
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=intestinal bacteria host metabolism" \
--data-urlencode "year_max=2010" \
--data-urlencode "page_size=100"
# current window
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=gut microbiome host metabolism" \
--data-urlencode "year_min=2021" \
--data-urlencode "page_size=100"
```
Beyond vocabulary, the two windows also reveal **conclusion shifts** — where older papers reached different findings, signalling a paradigm change or accumulating evidence — and **methodological evolution**, where observational work gave way to trials and then to meta-analyses. Both tell you how mature the evidence base is.
## What to check before you trust it
* **Confirm the old term actually returns results.** A term that returns nothing may be wrong rather than obsolete; check it against a paper you know exists.
* **Watch for terms that were never synonyms.** Adjacent-but-different concepts appearing in the old window will pull irrelevant work into your review if you treat them as equivalent.
* **Note regional and disciplinary variation.** Some vocabularies split rather than shift, and both remain current in different communities.
* **Record the term list in your methods.** It is part of the search strategy, and a reviewer who spots a missing synonym will ask.
## Related
Era-gated searches as one step in a full review.
Where a missed synonym does the most damage.
Filter ladder and the rest of the primitives.
Browse the gallery by persona.
# Check whether a finding has human evidence yet
Source: https://docs.consensus.app/use-cases/translational-readiness
Separate cell and animal work from human studies for a claim, and report the ratio — the number that tells you how translated a finding really is.
## What you get
A clear split of the evidence into preclinical and human tiers, with counts for each, the strongest study in each, and an explicit verdict on whether the claim has ever been tested in people.
## Who it's for
Discovery and translational teams deciding whether a finding is ready to build on, investors doing scientific diligence, and anyone evaluating a claim that sounds better-established than it is.
## Why the ratio is the finding
A large preclinical literature reads as strong evidence. Forty mouse studies and zero human trials is a very different situation from four of each — but a naive literature summary presents both as "well studied". Making the tier split explicit is the entire point of this workflow.
## How it works
One search restricted to preclinical designs, one restricted to human studies. Identical concept, deliberately different populations.
`study_types=animal` and `non-rct in vitro` isolate preclinical work. `human=true` with `rct`, `cohort study`, and `non-rct observational study` isolates the clinical tier.
Even when one is zero. Especially when one is zero.
Human studies often measure a surrogate rather than the outcome the preclinical work implied. A human trial of a biomarker is not a human trial of the disease outcome — say which you found.
Search for trials that ran and did not replicate the preclinical finding. This is the most informative and most frequently skipped search.
## The API calls
```bash theme={null}
# preclinical tier
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=senolytic clearance of senescent cells lifespan extension" \
--data-urlencode "study_types=animal,non-rct in vitro" \
--data-urlencode "page_size=100"
# human tier
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=senolytic therapy clinical trial outcomes older adults" \
--data-urlencode "human=true" \
--data-urlencode "study_types=rct,cohort study" \
--data-urlencode "page_size=100"
# failed translation
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=senolytic trial did not replicate preclinical finding null result" \
--data-urlencode "human=true" \
--data-urlencode "page_size=50"
```
## Reporting it
| Tier | Papers | Strongest study | Verdict |
| -------------------- | ------ | --------------- | ----------------------------- |
| In vitro | 34 | … | Consistent effect |
| Animal | 41 | … | Consistent across two species |
| Human observational | 3 | … | Association only |
| Human interventional | 0 | — | **Never tested in people** |
The bottom row is the output. Everything above it is context.
## What to check before you trust it
* **Zero human studies may mean zero, or may mean your query missed them.** Confirm with a different phrasing before reporting an absence — human trials often use a compound name where preclinical work uses a mechanism.
* **Watch the surrogate outcome.** "Tested in humans" for a biomarker change is not "tested in humans" for the clinical outcome.
* **Species matters.** Effects in short-lived model organisms translate especially poorly for anything involving lifespan or ageing.
* **Absence of failed trials is not evidence of success.** Negative results are under-published, so a clean record may reflect publication bias.
## Related
The full tiered dossier this check is one section of.
Score what you find on a consistent scale.
Filter ladder and the rest of the primitives.
Browse the gallery by persona.
# Find which journals to submit to
Source: https://docs.consensus.app/use-cases/where-to-submit
Identify the journals actually publishing work like yours, with their quartile, so you target a realistic venue first.
## What you get
A shortlist of journals that publish your kind of work, each with how many closely-related papers they carry, their SCImago quartile, and representative papers you can read to judge fit.
## Who it's for
Researchers choosing a submission target — especially early-career authors, and anyone publishing into a field they are new to. A mis-targeted submission costs a months-long rejection cycle before you learn anything.
## How it works
Query the specific contribution, not the broad topic. "Machine learning in healthcare" returns the wrong venues; "transformer models for ICU mortality prediction" returns the ones that would review you.
Paginate. The venue distribution in the top 20 results is noisier than across 200, and specialist journals surface further down.
Count `journal_name` across the deduplicated set, carrying `sjr_best_quartile` and `publisher_name`. Frequency tells you where this conversation happens; quartile tells you how hard the door is.
Rank once over five years and once over the last eighteen months. A journal that published heavily in 2019 and nothing since has moved on from the topic.
Fit is about framing and method, not keywords. The representative papers are the point of the exercise.
## The API call
```bash theme={null}
curl -G "https://api.consensus.app/v1/search" \
-H "x-api-key: $CONSENSUS_API_KEY" \
--data-urlencode "query=transformer models ICU mortality prediction electronic health records" \
--data-urlencode "year_min=2022" \
--data-urlencode "page_size=200"
```
Then aggregate client-side:
```python theme={null}
from collections import Counter
venues = Counter()
quartile = {}
for paper in results:
name = paper.get("journal_name")
if not name:
continue
venues[name] += 1
quartile[name] = paper.get("sjr_best_quartile")
for name, n in venues.most_common(15):
print(f"{n:>3} Q{quartile.get(name, '?')} {name}")
```
Add `open_access=true` if your funder mandates OA, and `sjr_max=1` to see only the top-quartile subset — but look at the unfiltered list first, or you will miss the specialist venue that is the actual best fit.
## What to check before you trust it
* **Frequency is not acceptance probability.** The journal publishing the most papers in your area may also reject the most. Use the list to build a realistic ladder — a reach, two solid targets, a fallback.
* **Check scope pages by hand.** Journals shift scope, launch sections, and close them. The literature lags those changes by a year or more.
* **Watch for a topic sitting mostly in conferences.** In fast-moving computational fields the venue that matters may not be a journal at all, and journal-only tallies will mislead you.
* **Quartile is a blunt instrument.** SCImago quartiles vary by subject category; a Q2 in a narrow specialist category can be more selective than a Q1 in a broad one.
## Related
Get the manuscript itself defensible before you submit it.
Make sure you are searching the terms this field actually uses.
Exhaustive sweep and the rest of the primitives.
Browse the gallery by persona.