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 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
Requires a signed-in Consensus account, over OAuth or an API key as a Bearer token.
Parameters
Filters
filters takes the same filters as search. 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, where1is Q1, the highest. Set1for Q1 journals only, or2for Q1 and Q2.sjr_min(integer, 1–4): the journal quartile floor. It excludes the better quartiles, so2keeps Q2–Q4. Don’t use it to ask for top-tier journals.domain,country,publisher_name,journal_name(strings)
Attachments
Attach up to 50 papers and up to 10 Library collections. The agent reads attached papers before it answers.citations[].paper_id in an earlier get_thread result.
Skills
Setskill to run a Skill, 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 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":
render_instructions that tell your assistant to share the Consensus link first and to wait for the final answer.
Library actions
The agent works in your Library when the brief asks it to. There’s no separate Library tool: put the request ininput_message, and name collections the way they appear in Consensus. If two collections share a name, also name the parent collection.
- 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_threadcall, 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
deeprun costs more than aprorun. 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_threadcall per second.