create_thread

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

Requires a signed-in Consensus account, over OAuth or an API key as a Bearer token.

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.
`attachments`	object	No	Papers and Library collections to focus the research on. See Attachments.

Filters

filters takes the same filters as search. 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)

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

{
  "paper_attachments": [{ "paper_id": "<paper_id>" }],
  "collection_ids": [123]
}

Paper IDs come from citations[].paper_id in an earlier get_thread result.

Response

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

{
  "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` and `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.
Rate limit: one create_thread call per second.

Introduction

Tools

Connect your client

Parameters

Filters

Attachments

Response

Example prompts

Good to know

​Parameters

​Filters

​Attachments

​Response

​Example prompts

​Good to know

Parameters

Filters

Attachments

Response

Example prompts

Good to know