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

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Systematic reviews: the search writes its own PRISMA record

> Run one question in every wording on the datasources of your protocol. The response has, for each datasource, the date, the wordings, and the counts, with the copies removed and each dropped record's reason, written up in PRISMA form.

A review team searches 5 databases for trials of one treatment. Its protocol asks for a report of each search: the database, the date, the exact wording, the number of records found, the duplicates removed, and the records excluded with the reason. Most of that is copied by hand from 5 screens, and a reviewer who runs the search again gets other numbers. This page builds a search that returns those numbers with its results, and that can be run again under the same conditions.

## The run in 6 steps

### Choose the datasources of the protocol

The catalog lists each datasource with the countries and the languages it covers, how it is reached, and which filters it applies itself. Your agent reads the catalog once and takes the ids of the datasources that the protocol names. A search takes up to 10 of them.

### Search in every wording, without a model

Send the question in each wording and each language that a trial can be reported in. With `deterministic_only` set to `true`, no model ranks the results or chooses datasources, so nothing in the list is a model's judgment.

```json Request body of search theme={"theme":"css-variables"}
{
  "query": "semaglutide \"heart failure with preserved ejection fraction\" randomized trial",
  "alternate_queries": [
    "semaglutide HFpEF randomised controlled trial",
    "GLP-1 receptor agonist heart failure preserved ejection fraction outcomes",
    "sémaglutide insuffisance cardiaque à fraction d'éjection préservée essai randomisé",
    "Semaglutid Herzinsuffizienz erhaltene Ejektionsfraktion randomisierte Studie"
  ],
  "datasources": ["FIRST_DATASOURCE_ID", "SECOND_DATASOURCE_ID", "THIRD_DATASOURCE_ID"],
  "published_from": "2019-01-01",
  "published_until": "2026-10-31",
  "max_candidates": 50,
  "deterministic_only": true,
  "record_form": "prisma"
}
```

Replace the 3 placeholders in `datasources` with ids from the catalog.

### Read the numbers that the protocol asks for

The response has the counts of the whole search and one entry for each datasource. This response is cut to those counts and to one datasource.

```json Part of the response theme={"theme":"css-variables"}
{
  "counts": {
    "found": 212,
    "returned": 50,
    "dropped": { "folded_copy": 61, "beyond_max_candidates": 101 }
  },
  "end_reason": "max_candidates",
  "datasources_searched": [
    {
      "id": "FIRST_DATASOURCE_ID",
      "outcome": { "kind": "delivered", "reason": "candidates" },
      "wordings": [0, 1, 2, 3, 4],
      "result_count": 148,
      "result_count_kind": "exact",
      "filters_applied": {
        "published_from": { "state": "native" },
        "published_until": { "state": "native" }
      }
    }
  ]
}
```

The numbers add up: 212 records were found, 61 were copies of a record already in the list, and 50 came back, with 101 more stored behind them. For each datasource the entry says which wordings ran, how many records it reported, whether that number is exact, and whether the datasource applied the date filter itself.

### Take the whole list, with the reason for each dropped record

The list is stored with the search. Its later pages have every record that did not come back in the first response, each with its `dropped_reason`. Your screening log starts from all 212 records, and none of them is missing without a reason.

### Hand the write-up to the reviewer

Because the request sent `record_form` as `prisma`, the response has `record`: the search written up in the form that a systematic review reports, as text and as structured data. It can go into the appendix of the review as it is.

### Run the search again next month

Send the same request with `published_from` set to the day after the last run. The records published since then come back, with their own counts and their own write-up. No model takes part, so a difference between 2 runs comes from the datasources and not from the search.

## What the peer reviewer can check

| The peer reviewer asks | What the search has |
| - | - |
| Which databases were searched, and when? | Each datasource, with the time of the search. |
| With which wording? | Every wording as it ran on each datasource, with the number of records it found there. |
| How many records were removed as duplicates? | The number of copies, and each copy with the record it was grouped behind. |
| Was a database left out? | The coverage gaps: a datasource that could not be searched, with the reason. |
| Would a second run find the same? | The request as it ran, with every default written out, and the version it ran under. |

## Know the limits

The search finds and counts. Which trials meet the criteria of the review is decided by your team, and the write-up covers the search and not the screening.

Copies are grouped inside one search. Across the runs of 2 months, match the records by their DOI, which each result has where the datasource declares it.

A full text behind a paywall is not fetched. The result says that the page asks for payment or a sign-in, and a person with access can upload the file.

A search is stored for 48 hours after its last use and for at most 30 days. Store the write-up and the list with the files of the review.

For the calls, see [See what a search covered and what it missed](https://docs.getclean.ai/find/search-receipt.md) and [Ask one question in 20 wordings](https://docs.getclean.ai/find/search-across-sources.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.