> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consensus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start: Threads

> Delegate a research question to the Consensus research agent and get back a cited answer, using the Threads endpoints of the Consensus API.

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, searching attached collections, and reading and writing your Library 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](https://docs.consensus.app/api-quickstart-search.md).

## 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.

> [card] [Crawl citations](#crawl-citations-from-a-seed-paper)
>
> Trace what a paper built on and the work that followed it.

> [card] [Read specific papers](#read-and-compare-specific-papers)
>
> Compare the methods and findings of papers you choose.

> [card] [Research an author](#research-an-author)
>
> Summarize an author's work on a topic and how it changed.

> [card] [Run deep research](#run-a-deep-literature-review)
>
> Get a structured literature review built from about 50 papers.

> [card] [Build on an earlier answer](#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.

```bash theme={null}
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 }
  }'
```

```json theme={null}
{
  "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": 5,
  "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`. A collection's id is the number in its web URL, `consensus.app/library/{id}/`.
* **`skill`:** run a named research workflow, a [Skill](https://docs.consensus.app/core-features/skills.md), 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

```bash theme={null}
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:

```json theme={null}
{
  "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. Quotes can come from the full text of any paper the analysis cites, paywalled papers from Consensus's [publisher partners](https://docs.consensus.app/get-started/full-text-access.md) 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](https://docs.consensus.app/core-features/skills.md) 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

```bash theme={null}
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.

## Work in your Library

With a personal API key, the agent can read and write your [Library](https://docs.consensus.app/core-features/library.md) 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.

| Action | Example `input_message` |
| - | - |
| List your collections, with their paper counts and your role on each | "List all of my Library collections and how many papers each has." |
| List the papers in a collection, filtered by publication year, date added, or a title, author, or journal match | "Which papers in my Sleep collection were published before 2020?" |
| Search within your collections | "What do the papers in my Sleep collection say about magnesium?" |
| Create a collection, at the top level or inside another one | "Create a collection called Magnesium inside my Sleep collection." |
| Save papers the agent found into a collection | "Find 10 RCTs on magnesium and sleep quality and save them to my Sleep collection." |
| Rename a collection | "Rename my Sleep collection to Sleep and Supplements." |

* **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](#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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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 }
}
```

### 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`.

```json theme={null}
{
  "input_message": "Check whether the citations in this paragraph support its claims: …",
  "mode": "deep",
  "skill": "verify-citations"
}
```

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.

```json theme={null}
{
  "input_message": "Find 10 randomized controlled trials on magnesium supplementation and sleep quality in adults, summarize their findings, and save them to a new collection called Magnesium and Sleep."
}
```

### Audit and tidy a collection

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

```json theme={null}
{
  "input_message": "List the papers in my Sleep collection published before 2015, summarize which of their conclusions newer work has overturned, then rename the collection to Sleep - foundational."
}
```

### 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.

```json theme={null}
{
  "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](https://docs.consensus.app/api-plans-and-access.md#how-calls-are-counted).
* **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

> [card] [Start a Thread](https://docs.consensus.app/api-reference/start-a-thread.md)
>
> `POST /v1/threads`

> [card] [Poll a Thread](https://docs.consensus.app/api-reference/poll-a-thread.md)
>
> `GET /v1/threads/{thread_id}`

> [card] [Add a follow-up](https://docs.consensus.app/api-reference/add-a-follow-up.md)
>
> `POST /v1/threads/{thread_id}/interactions`

> [card] [List historical Threads](https://docs.consensus.app/api-reference/list-historical-threads.md)
>
> `GET /v1/threads`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.