Skip to main content
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. 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. A pro run usually finishes in under a minute, and a deep run takes a few minutes.
1

Create a Thread

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

Poll until it's done

GET /v1/threads/{thread_id} until status is idle (answer ready) or failed. Wait poll_after_seconds between polls: 5 seconds for pro, 20 for deep.
3

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.
  • 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. A collection’s id is the number in its web URL, consensus.app/library/{id}/.
  • skill: run a named research workflow, a Skill, instead of the agent’s open-ended plan: literature-review, citation-snowballing, find-citations, or verify-citations. It requires mode set to deep. Leave it unset for normal research.

Poll for the answer

While the run is going, status is running. When it’s idle, the latest interaction carries the answer:
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. Quotes can come from the full text of any paper the analysis cites, paywalled papers from Consensus’s publisher partners included.
  • 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 agent_trace, a plain-English list of the steps the agent took. It’s written for display, so don’t parse it.
  • Skill: an interaction that ran a Skill carries skill, such as literature-review or verify-citations: the one requested, otherwise the one the agent chose itself. It’s omitted when none applies.
  • Earlier turns: only the latest interaction carries response and citations. Pass interaction_id to read an earlier one.
  • Institutional full-text links: on a paid plan, if you’ve selected your institution in Consensus settings, citations can include an institutional_access_url that opens the full text through your library. Only the first 50 distinct DOIs are looked up.

Ask a follow-up

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.

Work in your Library

With a personal API key, the agent can read and write your Library as part of a Thread. Ask in plain language in input_message, and name collections the way they appear in Consensus. If two collections share a name, also name the parent collection, for example “the Methods collection inside Sleep”. There are no separate Library endpoints.
  • Saves don’t pause for confirmation. The agent saves papers as soon as you ask, and the answer says how many it added and how many were already there.
  • No surprise collections. The agent creates a collection only when you ask for one. If you name a collection that doesn’t exist, it reports it as not found instead of creating it.
  • Removing, deleting, and moving are web-only. These need a confirmation step, so they’re available only in the Consensus web app. Over the API, the agent tells you to make the change there.
  • Listings stop at 100 collections. In a larger Library, the rest are summarized as “and N more”, and you can’t page through them.
  • Personal keys only. An organization API key has no Library, so its Threads can’t list or change collections.
The Thread’s response reports what changed.

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.

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.

Research an author

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

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.

Run a skill

Set skill to run a named workflow, on a new Thread or a follow-up. Skills run in deep mode, so set mode to deep too. find-citations and verify-citations work on a draft, so put the draft text in input_message.
A request with skill is refused with 422 if mode isn’t deep, if you use an organization API key, or if the skill needs input the request didn’t include. If skills aren’t enabled for your account yet, it returns 403 feature_not_allowed.

Save papers to a collection

The agent runs the research, then saves the papers it found into a collection you name. Ask for a new collection explicitly if you want one.

Audit and tidy a collection

The agent lists a collection’s papers with filters, reads them, and renames the collection.

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.

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