> ## 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`](/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`](/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, create or rename one, and save papers it found into one

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](/consensus-mcp#connect-your-client).
</Note>

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

### Filters

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

* `year_min`, `year_max`, `month_min`, `month_max` (integers)
* `study_types` (array or comma-separated string, 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_min`, `sjr_max` (journal quartile, 1–4)
* `domain`, `country`, `publisher_name`, `journal_name` (strings)

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

### 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`](/mcp-tools/get-thread#response) result.

## 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": 30,
  "max_wait_seconds": 180,
  "next_steps": "Wait at least 30 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`](/mcp-tools/get-thread) and [`add_to_thread`](/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: 30 seconds. Polling faster doesn't speed up the agent. |
| `max_wait_seconds` | When to stop polling: 180 for `pro`, 600 for `deep`. |

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

## 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 minutes 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](/mcp-plans-and-access#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.