- Search: the
searchtool returns ranked papers in one call. Your assistant reads them and writes the answer. - Threads: the thread tools hand the whole research question to the Consensus research agent. The agent searches, reads the papers, and writes a cited answer. Your assistant starts the Thread, waits for it, and shows the result.
Search vs Threads
Need a quick lookup, or papers for your assistant to reason over? Use search. Need a researched, cited answer to a question that takes several steps? Use a Thread.
Search
Your assistant callssearch with a query and any filters you asked for, then answers from the ranked papers it gets back.
Try asking:
- “Find RCTs and meta-analyses since 2020 on cognitive behavioral therapy for anxiety”
- “Search for human studies on gut microbiome and mental health with at least 100 participants”
- “Recent research on large language model hallucination from Q1 journals”
search tool reference for every filter.
Read whole papers
When the abstract and excerpts aren’t enough, your assistant can read a paper’s complete text. Each search result shows anid: line, marked full text available when the paper is open access and get_full_text is available to you. Your assistant passes up to 3 of those ids, a Thread citation’s paper_id, or DOIs, to get_full_text and gets each paper back as Markdown. It costs 1 credit per paper returned and needs a paid plan.
- “Read the methods section of the largest RCT in those results.”
- “Get the full text of 10.2903/j.efsa.2024.9100 and list every dose it reports.”
Threads
Threads are asynchronous. Apro run usually finishes in under a minute, and a deep run takes a few minutes.
1
Start a Thread
Your assistant calls
create_thread with the complete research brief. It returns a thread_id and a link to the Thread in Consensus right away, with status: "running".2
Wait for the answer
Your assistant calls
get_thread about every 5 seconds for pro and every 20 seconds for deep, until status is idle (answer ready) or failed. A pro run usually finishes in under a minute. A deep run takes about 2 to 4 minutes, and occasionally up to about 10.3
Show the result
When the Thread is
idle, get_thread returns the analysis as a ready-to-write markdown document with a References section. Most assistants write it to a file, artifact, or canvas and reply with a short summary plus the Consensus link.4
Ask a follow-up
add_to_thread continues the same Thread. The agent keeps the earlier context, so you don’t need to restate it.find_threads lists your Threads and can match on title.
What you can ask a Thread
Each of these takes several research steps, which a single search can’t do.Crawl citations
“Start from Cong et al. 2013, the first report of CRISPR-Cas9 editing in mammalian cells. Trace the work it built on and the most-cited papers that followed, and summarize how the method evolved.”
Research an author
“Summarize Walter Willett’s research on dietary fat and heart disease, and how his conclusions changed over time.”
Run deep research
“Do a deep literature review on GLP-1 receptor agonists and cardiovascular outcomes. Cover mechanisms, the major trials, safety signals, and open questions.”
Save papers to your Library
“Find 10 RCTs on magnesium and sleep quality and save them to my Sleep collection.”
Build on an earlier answer
“Of the trials you cited, keep only RCTs with more than 100 participants. Does the conclusion change?”
Good to know
- Account: the thread tools appear only for a signed-in Consensus account, over OAuth or an API key as a Bearer token. Without an account, your assistant sees only
search. - Deep mode:
deepreads about 50 papers and writes a longer, structured report. It requires a paid plan, and your assistant uses it only when you ask for a deep or comprehensive review. - Cost: search costs one call per 100 papers returned, and
get_full_text1 credit per paper returned. A Thread draws from the same monthly calls and is charged by the amount of work the agent does, so adeeprun costs more than aprorun. A failed run costs nothing. See plans and access. - In Consensus: a Thread started from your account also appears in Consensus, with the interactive consensus meter and citation graph. Open it from the
urllink. - Same as the API: the thread tools run the same research agent as the Threads API.
Tool reference
search
Find ranked papers for a query in one call.
get_full_text
Read the complete text of open-access papers.
create_thread
Start a Thread with the research agent.
get_thread
Poll a Thread and read the cited answer.
add_to_thread
Ask a follow-up in an existing Thread.
find_threads
List your Threads and find an earlier one.