> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consensus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                          |

<Tip>
  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.
</Tip>

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

<Steps>
  <Step title="Decompose before retrieving">
    Split the question into subquestions — mechanism, population, outcome, competing explanations. Generate several phrasings per subquestion covering synonyms and adjacent terminology.
  </Step>

  <Step title="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](#rate-limits-and-result-caps) below.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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
```

<Note>
  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.
</Note>

## 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+                   |

<Warning>
  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.
</Warning>

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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Tip>
  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."
</Tip>

## What makes a good Consensus use case

<AccordionGroup>
  <Accordion title="The question has an evidence base" icon="magnifying-glass">
    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.
  </Accordion>

  <Accordion title="The population can be narrowed with filters" icon="filter">
    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.
  </Accordion>

  <Accordion title="The output is verifiable" icon="circle-check">
    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.
  </Accordion>

  <Accordion title="It decomposes into many searches" icon="grid-2">
    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.
  </Accordion>

  <Accordion title="Poor fit: single-fact lookups and non-research questions" icon="circle-xmark">
    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*.
  </Accordion>
</AccordionGroup>

## 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     |

<CardGroup cols={2}>
  <Card title="Back to the gallery" icon="grid-2" href="/use-cases">
    Browse all 12 use cases by persona.
  </Card>

  <Card title="Search endpoint reference" icon="sliders" href="/api-reference/query-for-relevant-papers">
    Every filter, the full response schema, and an interactive playground.
  </Card>
</CardGroup>