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

# get_thread

> The Consensus MCP get_thread tool: poll a Thread and read the research agent's cited answer when it's ready.

`get_thread` polls a Thread. While the agent works, `status` is `running`. When it's `idle`, the result carries the agent's answer: markdown with inline citations, the grounding quotes, the cited papers, and a ready-to-write document.

Your assistant calls it after [`create_thread`](https://docs.consensus.app/mcp-tools/create-thread) or [`add_to_thread`](https://docs.consensus.app/mcp-tools/add-to-thread), about every 5 seconds for `pro` and every 20 seconds for `deep`. A `pro` run usually finishes in under a minute. A `deep` run takes about 2 to 4 minutes, and occasionally up to about 10. Polling faster doesn't speed up the agent.

> [!NOTE]
>
> Requires a signed-in Consensus account, over OAuth or an [API key as a Bearer token](https://docs.consensus.app/consensus-mcp.md#connect-your-client). You can read only your own Threads.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `thread_id` | string | Yes | The `thread_id` from `create_thread` or [`find_threads`](https://docs.consensus.app/mcp-tools/find-threads). |
| `interaction_id` | string | No | Return only this interaction, for example the run you just started. Omit to return every interaction in the Thread. |
| `include_trace` | boolean | No | Set to `true` to add `agent_trace`, a plain-English list of the steps the agent took (the searches it ran, the papers it read). Off by default to keep polls light. |

## Response

```json theme={null}
{
  "thread_id": "<thread_id>",
  "title": "Creatine dose and working memory in healthy adults",
  "filename": "Creatine dose and working memory in healthy adults.md",
  "status": "idle",
  "url": "https://consensus.app/search/creatine-dose-and-working-memory-in-healthy-adults/<thread_id>/",
  "message_for_user": "Your Consensus research thread is ready. [View this in Consensus](https://consensus.app/search/…)",
  "interactions": [
    {
      "interaction_id": "<interaction_id>",
      "input_message": "What dose of creatine improves working memory in healthy adults…",
      "status": "idle",
      "mode": "pro",
      "response": "Short-term loading at about 20 g/day improved working memory in some trials [[1.1]](https://consensus.app/papers/…) …",
      "document": "# Creatine dose and working memory in healthy adults\n\n… \n\n## References\n…",
      "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, "eligible": 40, "included": 18 },
      "step_count": 12
    }
  ]
}
```

Illustrative and trimmed. The payload also carries `render_instructions` and a `schema_note` for your assistant.

| Field | Description |
| - | - |
| `status` | `running`, `idle` (answer ready), or `failed`. Matches the latest interaction. |
| `url` | The Thread in Consensus, where the interactive consensus meter and citation graph live. Empty for a Thread started with an organization API key. |
| `filename` | A file-safe name your assistant can save `document` under. |
| `interactions[].skill` | The [Skill](https://docs.consensus.app/core-features/skills.md) the interaction ran, such as `literature-review` or `verify-citations`: the one requested, otherwise the one the agent chose itself. Absent when none applies. |
| `interactions[].response` | The answer in markdown. A marker like `[1.1]` cites quote 1 from paper 1, and a bare `[1]` cites the paper without a quote. Each marker links to its paper. |
| `interactions[].document` | A complete markdown document: `response`, a Consensus disclaimer, and a References section. Present only when the interaction is `idle`. |
| `interactions[].citations` | The cited papers, numbered by first citation in `response`. Each `snippets[].marker` matches a marker in the text. On a paid plan, if you've selected your institution in Consensus settings, a citation can include an `institutional_access_url` that opens the full text through your library, and its entry in the `document` References links to it. Pass a citation's `paper_id` to [`get_full_text`](https://docs.consensus.app/mcp-tools/get-full-text) to read that paper in full. |
| `interactions[].stats` | Papers `retrieved`, `eligible`, and `included` in the answer. |
| `interactions[].step_count` | How many steps the agent took. Matches the steps listed in `agent_trace`. |
| `interactions[].agent_trace` | The agent's steps as markdown bullets, then the paper funnel. Present only with `include_trace=true`. Written for display, so don't parse it: the wording can change. |

Only an `idle` interaction carries the full `response` and `citations`. Evidence-strength scores, top authors, the results timeline, the research-gap matrix, and the search funnel come back as text and tables inside `response` and `document`.

## How assistants show the result

`get_thread` tells your assistant to:

1. Share the **View this in Consensus** link first.
2. Write `document` to the file named in `filename`, or render it in an artifact, canvas, or side panel, instead of pasting it into chat.
3. Keep every citation marker exactly as written.
4. Reply in chat with a 2–3 sentence summary and the Consensus link.

## Good to know

* **Rate limit:** up to three `get_thread` calls per second.
* **Wrong interaction:** an `interaction_id` from another Thread returns an error. Poll with the `thread_id` alone to get the latest interaction.


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