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. Apro 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 ininput_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.deepreads more papers and writes a longer, structured report.filters: the same filters asGET /v1/search, such asyear_min,study_types,human, andsjr_max. They apply to every search the agent runs.attachments: focus the research on up to 50paper_idsor 10 Librarycollection_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, orverify-citations. It requiresmodeset todeep. Leave it unset for normal research.
Poll for the answer
status is running. When it’s idle, the latest interaction carries the answer:
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 forproand 10 minutes fordeep. - Agent steps: add
include_trace=trueto getagent_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 asliterature-revieworverify-citations: the one requested, otherwise the one the agent chose itself. It’s omitted when none applies. - Earlier turns: only the latest interaction carries
responseandcitations. Passinteraction_idto 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_urlthat opens the full text through your library. Only the first 50 distinct DOIs are looked up.
Ask a follow-up
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 ininput_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.
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 withattachments.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
Setmode 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
Setskill 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.
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 toPOST /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.
modecontrols the effort, so adeeprun costs more than aprorun. 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/threadsPoll a Thread
GET /v1/threads/{thread_id}Add a follow-up
POST /v1/threads/{thread_id}/interactionsList historical Threads
GET /v1/threads