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

# create_thread

> The Consensus MCP create_thread tool: start a Thread that hands a research question to the Consensus research agent.

`create_thread` starts a Thread: it hands a research question to the Consensus research agent and returns right away. The agent plans and runs many searches, reads full text, follows citations forward and backward, and writes a cited answer. Your assistant then polls [`get_thread`](https://docs.consensus.app/mcp-tools/get-thread) for the result.

Use it for questions that need synthesis or analysis: what the evidence says, comparisons, mechanisms, literature reviews, and multi-step research tasks. For a single lookup of papers, use [`search`](https://docs.consensus.app/mcp-tools/search).

The research agent can:

* Search semantically and by keyword, and look up an exact paper by DOI, title, or author
* Find papers by an author
* Crawl citations forward and backward, and expand to influential, seminal, or similar papers
* Read the full text of papers and quote them
* Search attached papers and Library collections
* List your Library collections and the papers in one (filtered by publication year or date added), create or rename a collection, and save papers it found into one. See [Library actions](#library-actions)

It doesn't browse the open web and doesn't ask clarifying questions.

> [!NOTE]
>
> Requires a signed-in Consensus account, over OAuth or an [API key as a Bearer token](https://docs.consensus.app/consensus-mcp.md#connect-your-client).

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `input_message` | string | Yes | The complete research brief, up to 10,000 characters. Include the question, scope, population, timeframe, comparisons, constraints, and the output you want. |
| `mode` | string | No | `pro` (default) reads about 20 papers and fits almost every question. `deep` reads about 50 papers, up to 100, and writes a structured literature review. `deep` requires a paid plan. |
| `filters` | object | No | Search filters applied to every search the agent runs. See [Filters](#filters). |
| `attachments` | object | No | Papers and Library collections to focus the research on. See [Attachments](#attachments). |
| `skill` | string | No | A named research workflow to run. See [Skills](#skills). |

### Filters

`filters` takes the same filters as [`search`](https://docs.consensus.app/mcp-tools/search#parameters). Every key is optional:

* `year_min`, `year_max`, `month_min`, `month_max` (integers)
* `study_types` (array, for example `["rct", "meta-analysis"]`)
* `human`, `controlled`, `open_access`, `exclude_preprints`, `clinical_guideline` (booleans)
* `sample_size_min`, `citation_min`, `duration_min`, `duration_max` (integers)
* `sjr_max` (integer, 1–4): the journal quartile ceiling, where `1` is Q1, the highest. Set `1` for Q1 journals only, or `2` for Q1 and Q2.
* `sjr_min` (integer, 1–4): the journal quartile floor. It excludes the better quartiles, so `2` keeps Q2–Q4. Don't use it to ask for top-tier journals.
* `domain`, `country`, `publisher_name`, `journal_name` (strings)

```json theme={null}
{ "year_min": 2020, "study_types": ["rct", "meta-analysis"], "human": true, "sjr_max": 2 }
```

> [!WARNING]
>
> Filters you pass replace the agent's own filter choices for every search in the run. Include every constraint you want enforced, such as `study_types` alongside `sjr_max`. Or leave `filters` empty and state the constraints in `input_message`.

### Attachments

Attach up to 50 papers and up to 10 Library collections. The agent reads attached papers before it answers.

```json theme={null}
{
  "paper_attachments": [{ "paper_id": "<paper_id>" }],
  "collection_ids": [123]
}
```

Paper IDs come from `citations[].paper_id` in an earlier [`get_thread`](https://docs.consensus.app/mcp-tools/get-thread#response) result.

### Skills

Set `skill` to run a [Skill](https://docs.consensus.app/core-features/skills.md), a named research workflow, instead of the agent's open-ended plan. Set it only when you ask for one of these workflows, and set `mode` to `deep` too:

| Skill | What it does |
| - | - |
| `literature-review` | Synthesizes the literature on a topic: searches from several angles, follows citations, and investigates contradictory evidence. |
| `citation-snowballing` | Expands from known seed papers by following backward and forward citations. Attach or name the seed papers. |
| `find-citations` | Finds research to support, qualify, or challenge the uncited claims in a draft. Put the draft in `input_message`. |
| `verify-citations` | Checks whether the citations already in a draft support their claims, and suggests the smallest fix for weak ones. Put the cited draft in `input_message` or attach it. |

> [!NOTE]
>
> `skill` appears only when skills are enabled for your account. It isn't available with an organization API key. A call with `skill` returns an error if `mode` isn't `deep`, or if the skill needs input the call didn't include.

## Response

`create_thread` returns as soon as the agent starts, with `status: "running"`:

```json theme={null}
{
  "thread_id": "<thread_id>",
  "interaction_id": "<interaction_id>",
  "created_at": "2026-10-09T14:00:00Z",
  "title": "Creatine dose and working memory in healthy adults",
  "status": "running",
  "mode": "pro",
  "url": "https://consensus.app/search/creatine-dose-and-working-memory-in-healthy-adults/<thread_id>/",
  "message_for_user": "Consensus research thread started: [View this in Consensus](https://consensus.app/search/…)",
  "poll_after_seconds": 5,
  "max_wait_seconds": 180,
  "next_steps": "Wait 5 seconds (use a sleep/timeout) between each get_thread(thread_id='<thread_id>') call. …"
}
```

Trimmed. The payload also carries `render_instructions` that tell your assistant to share the Consensus link first and to wait for the final answer.

| Field | Description |
| - | - |
| `thread_id` | Pass to [`get_thread`](https://docs.consensus.app/mcp-tools/get-thread) and [`add_to_thread`](https://docs.consensus.app/mcp-tools/add-to-thread). |
| `interaction_id` | The run this call started. Pass to `get_thread` to read only this run. |
| `url` | The Thread in Consensus. Empty for a Thread started with an organization API key, which has no Consensus page. |
| `poll_after_seconds` | Wait this long between `get_thread` calls: 5 seconds for `pro`, 20 for `deep`. Polling faster doesn't speed up the agent. |
| `max_wait_seconds` | When to stop polling: 180 for `pro`, 600 for `deep`. |

## Library actions

The agent works in your [Library](https://docs.consensus.app/core-features/library.md) when the brief asks it to. There's no separate Library tool: put the request in `input_message`, and name collections the way they appear in Consensus. If two collections share a name, also name the parent collection.

| Action | Example request |
| - | - |
| List collections, with their paper counts and your role on each | "List all of my Library collections and how many papers each has." |
| List a collection's papers, filtered by publication year, date added, or a title, author, or journal match | "Which papers did I add to my Sleep collection last month?" |
| Create a collection, at the top level or inside another one | "Create a collection called Magnesium inside my Sleep collection." |
| Save papers into a collection | "Find 10 RCTs on magnesium and sleep quality and save them to my Sleep collection." |
| Rename a collection | "Rename my Sleep collection to Sleep and Supplements." |

* The agent saves papers without pausing for confirmation, and creates a collection only when you ask for one. An unknown collection name comes back as not found.
* Removing papers, deleting a collection, and moving a collection need a confirmation step, so they're available only in the Consensus web app.
* A listing stops at 100 collections. The rest are summarized as "and N more", with no way to page through them.
* To focus a later Thread on a collection, pass its id as `attachments.collection_ids`. The id is the number in the collection's web URL, `consensus.app/library/{id}/`.
* A Thread started with an organization API key has no Library, so it can't list or change collections.

## Example prompts

* "Start a Consensus research thread: what dose of creatine improves working memory in healthy adults, and how strong is the evidence?"
* "Use Consensus to do a deep literature review on GLP-1 receptor agonists and cardiovascular outcomes since 2015."
* "Trace the citations from Cong et al. 2013 and summarize how CRISPR-Cas9 editing evolved."
* "Find 10 RCTs on magnesium and sleep quality and save them to my Sleep collection."
* "List all of my Consensus Library collections with their names and number of papers."

## Good to know

* **One brief per request.** Put the whole request in one `create_thread` call, including ordered sub-tasks. Splitting it into a chain of Threads gives worse results and adds a full agent run per step.
* **Cost:** charged by the amount of work the agent does, so a `deep` run costs more than a `pro` run. A failed run costs nothing. While the Thread runs, its maximum possible cost counts as used. If that doesn't fit under your plan's limit, the call returns an error. See [plans and access](https://docs.consensus.app/mcp-plans-and-access.md#how-calls-are-counted).
* **Rate limit:** one `create_thread` call per second.


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