Quick start: Threads

The Threads endpoints hand a research question to the Consensus research agent. The agent searches the literature, reads the papers, and writes a markdown answer with citations. You create a Thread, poll it until the answer is ready, and add follow-ups that keep the earlier context.

Search vs Threads

Search returns papers and leaves the reasoning to your code. A Thread hands the whole research task to an agent, which runs many steps and writes the answer for you.

	Search	Threads
You get back	A list of papers with abstracts and metadata	A list of papers, a written analysis, a reasoning trace (with `include_trace=true`), and citations with grounding quotes
Functionality	Semantic paper search with filters	Search, citation crawls, author search, finding specific papers, reading full papers, and searching attached collections
Steps per request	One	Many
Timing	Synchronous	Asynchronous
Follow-ups	Each request stands alone	Ask follow-up questions that build on earlier answers

Need the raw papers for your own pipeline, or a quick lookup? Use Search.

What you can ask a Thread

Each of these needs several research steps in one request, which Search can’t do. Click a card for the request body.

Crawl citations

Trace what a paper built on and the work that followed it.

Read specific papers

Compare the methods and findings of papers you choose.

Research an author

Summarize an author’s work on a topic and how it changed.

Run deep research

Get a structured literature review built from about 50 papers.

Build on an earlier answer

Narrow or extend the last answer without starting over.

How it works

Threads are asynchronous. Each run takes minutes, not seconds.

Create a Thread

POST /v1/threads starts the run and returns a thread_id right away, with status: "running".

Poll until it's done

GET /v1/threads/{thread_id} until status is idle (answer ready) or failed. Wait poll_after_seconds (30) between polls.

Ask a follow-up

POST /v1/threads/{thread_id}/interactions continues the Thread. Poll again for the new answer.

Create a Thread

Send the complete research brief in input_message. The agent doesn’t ask clarifying questions, so include the whole task in one message.

curl -X POST "https://api.consensus.app/v1/threads" \
  -H "x-api-key: $CONSENSUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_message": "What dose of creatine improves working memory in healthy adults, and how strong is the evidence?",
    "mode": "pro",
    "filters": { "year_min": 2010, "human": true }
  }'

{
  "thread_id": "<thread_id>",
  "interaction_id": "<interaction_id>",
  "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>/",
  "poll_after_seconds": 30,
  "max_wait_seconds": 180
}

mode: controls how much effort the agent spends. pro (the default) fits most questions. deep reads more papers and writes a longer, structured report.
filters: the same filters as GET /v1/search, such as year_min, study_types, human, and sjr_max. They apply to every search the agent runs.
attachments: focus the research on up to 50 paper_ids or 10 Library collection_ids.

Poll for the answer

curl "https://api.consensus.app/v1/threads/<thread_id>" -H "x-api-key: $CONSENSUS_API_KEY"

While the run is going, status is running. When it’s idle, the latest interaction carries the answer:

{
  "thread_id": "<thread_id>",
  "title": "Creatine dose and working memory in healthy adults",
  "status": "idle",
  "url": "https://consensus.app/search/creatine-dose-and-working-memory-in-healthy-adults/<thread_id>/",
  "interactions": [
    {
      "interaction_id": "<interaction_id>",
      "status": "idle",
      "mode": "pro",
      "response": "Short-term loading at about 20 g/day improved working memory in some trials [1.1] …",
      "citations": [
        {
          "n": 1,
          "paper_id": "<paper_id>",
          "title": "Creatine and improvement in cognitive function: Evaluation of a health claim …",
          "year": 2024,
          "journal": "EFSA Journal",
          "url": "https://consensus.app/papers/…",
          "snippets": [
            { "marker": "1.1", "quote": "…", "section": "Weighing of the evidence" }
          ]
        }
      ],
      "stats": { "retrieved": 120, "screened": 40, "included": 18 }
    }
  ]
}

Illustrative and trimmed. In response, a marker like [1.1] cites quote 1 from paper 1, and a bare [1] cites the paper without a quote. Each citations[].snippets[].marker matches a marker in the text.

How long to wait: stop polling after max_wait_seconds, about 3 minutes for pro and 10 minutes for deep.
Agent steps: add include_trace=true to get a readable log of what the agent did.
Earlier turns: only the latest interaction carries response and citations. Pass interaction_id to read an earlier one.

Ask a follow-up

curl -X POST "https://api.consensus.app/v1/threads/<thread_id>/interactions" \
  -H "x-api-key: $CONSENSUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input_message": "Do the results differ for adults over 60?" }'

The agent already has the earlier turns, so don’t restate them. A follow-up sent while the latest interaction is still running returns 409. Wait until the Thread is idle or failed, then send it. To find earlier Threads, GET /v1/threads lists yours newest first. Pass query to match on title.

Example requests

Each example shows the request body. Send it the same way as in Create a Thread, then poll for the answer.

Crawl citations from a seed paper

The agent follows the citation graph backward and forward from a paper you name.

{
  "input_message": "Start from Cong et al. 2013, the first report of CRISPR-Cas9 genome editing in mammalian cells. Trace the earlier work it built on and the most-cited papers that followed it, and summarize how the method evolved."
}

Read and compare specific papers

Attach papers with attachments.paper_ids, and the agent reads them before it answers. Paper IDs come from citations[].paper_id in an earlier Thread.

{
  "input_message": "Compare the methods, sample sizes, and effect sizes across these papers, and explain where their conclusions disagree.",
  "attachments": { "paper_ids": ["<paper_id_1>", "<paper_id_2>", "<paper_id_3>"] }
}

Research an author

The agent looks up papers by a named author, then synthesizes them.

{
  "input_message": "Summarize Walter Willett's research on dietary fat and heart disease, and how his conclusions changed over time."
}

Run a deep literature review

Set mode to deep for a structured report built from about 50 papers. A deep run takes up to about 10 minutes and requires a paid plan.

{
  "input_message": "Write a literature review on GLP-1 receptor agonists and cardiovascular outcomes. Cover mechanisms, the major trials, safety signals, and open questions.",
  "mode": "deep",
  "filters": { "year_min": 2015 }
}

Build on an earlier answer

Send a follow-up to POST /v1/threads/{thread_id}/interactions. The agent reads the earlier turns, so you can refer to them directly.

{
  "input_message": "Of the trials you cited, keep only the randomized controlled trials with more than 100 participants. Does the conclusion change?"
}

Good to know

Cost: a Thread draws from the same monthly calls as search, and it’s charged by the amount of work the agent does. mode controls the effort, so a deep run costs more than a pro run. A failed run costs nothing. See plans and access.
Rate limits: one request per second, except polling a Thread, which allows three per second.
Don’t retry blindly on 5xx. The Thread or follow-up may already have been created. List your Threads or poll the Thread before you send it again.

Endpoint reference

Start a Thread

POST /v1/threads

Poll a Thread

GET /v1/threads/{thread_id}

Add a follow-up

POST /v1/threads/{thread_id}/interactions

List historical Threads

GET /v1/threads

​Search vs Threads

​What you can ask a Thread

Crawl citations

Read specific papers

Research an author

Run deep research

Build on an earlier answer

​How it works

​Create a Thread

​Poll for the answer

​Ask a follow-up

​Example requests

​Crawl citations from a seed paper

​Read and compare specific papers

​Research an author

​Run a deep literature review

​Build on an earlier answer

​Good to know

​Endpoint reference

Start a Thread

Poll a Thread

Add a follow-up

List historical Threads

Search vs Threads

What you can ask a Thread

How it works

Create a Thread

Poll for the answer

Ask a follow-up

Example requests

Crawl citations from a seed paper

Read and compare specific papers

Research an author

Run a deep literature review

Build on an earlier answer

Good to know

Endpoint reference