> ## 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, 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](/api-quickstart-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.

<CardGroup cols={2}>
  <Card title="Crawl citations" icon="network" href="#crawl-citations-from-a-seed-paper">
    Trace what a paper built on and the work that followed it.
  </Card>

  <Card title="Read specific papers" icon="file-text" href="#read-and-compare-specific-papers">
    Compare the methods and findings of papers you choose.
  </Card>

  <Card title="Research an author" icon="user" href="#research-an-author">
    Summarize an author's work on a topic and how it changed.
  </Card>

  <Card title="Run deep research" icon="layers" href="#run-a-deep-literature-review">
    Get a structured literature review built from about 50 papers.
  </Card>

  <Card title="Build on an earlier answer" icon="messages-square" href="#build-on-an-earlier-answer">
    Narrow or extend the last answer without starting over.
  </Card>
</CardGroup>

## How it works

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

<Steps>
  <Step title="Create a Thread">
    `POST /v1/threads` starts the run and returns a `thread_id` right away, with `status: "running"`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Ask a follow-up">
    `POST /v1/threads/{thread_id}/interactions` continues the Thread. Poll again for the new answer.
  </Step>
</Steps>

## 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": 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

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

* **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

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

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

### 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](/api-plans-and-access#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

<CardGroup cols={2}>
  <Card title="Start a Thread" icon="plus" href="/api-reference/start-a-thread">
    `POST /v1/threads`
  </Card>

  <Card title="Poll a Thread" icon="refresh-cw" href="/api-reference/poll-a-thread">
    `GET /v1/threads/{thread_id}`
  </Card>

  <Card title="Add a follow-up" icon="message-square-plus" href="/api-reference/add-a-follow-up">
    `POST /v1/threads/{thread_id}/interactions`
  </Card>

  <Card title="List historical Threads" icon="list" href="/api-reference/list-historical-threads">
    `GET /v1/threads`
  </Card>
</CardGroup>


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