Best practices

Every use case in the gallery 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.

Decompose before retrieving

Split the question into subquestions — mechanism, population, outcome, competing explanations. Generate several phrasings per subquestion covering synonyms and adjacent terminology.

Pace them to your rate limit

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 below.

Deduplicate on DOI

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.

Keep the pre- and post-merge counts

You will need both to describe your coverage, and a sharp drop tells you your phrasings were near-duplicates.

Filter ladder

# 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

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.

Cite only what came back in this session

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.

Count three things separately

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.

Detect the plan cap and report it

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.

Confirm each result before moving on

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.

Require a retrievable link for every citation

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

The question has an evidence base

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 population can be narrowed with filters

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.

The output is verifiable

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.

It decomposes into many searches

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.

Poor fit: single-fact lookups and non-research questions

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

Back to the gallery

Browse all 12 use cases by persona.

Search endpoint reference

Every filter, the full response schema, and an interactive playground.

Overview

Use cases

The five patterns

Fan-out and merge

Filter ladder

Exhaustive sweep

Rate limits and result caps

Grounding and auditability

The audit log

What makes a good Consensus use case

Surface differences worth knowing

Back to the gallery

Search endpoint reference

​The five patterns

​Fan-out and merge

​Filter ladder

​Exhaustive sweep

​Rate limits and result caps

​Grounding and auditability

​The audit log

​What makes a good Consensus use case

​Surface differences worth knowing

Back to the gallery

Search endpoint reference

The five patterns

Fan-out and merge

Filter ladder

Exhaustive sweep

Rate limits and result caps

Grounding and auditability

The audit log

What makes a good Consensus use case

Surface differences worth knowing