Skip to main content
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
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

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, 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)
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.
Paper IDs come from citations[].paper_id in an earlier get_thread result.

Skills

Set skill 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":
Trimmed. The payload also carries 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 in input_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_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.
  • Rate limit: one create_thread call per second.