> ## 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`](/mcp-tools/create-thread) or [`add_to_thread`](/mcp-tools/add-to-thread), about every 30 seconds. A `pro` run usually finishes within about 3 minutes, and a `deep` run within about 10 minutes. Polling faster returns the same `running` result and doesn't speed up the agent.

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

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `thread_id` | string | Yes | The `thread_id` from `create_thread` or [`find_threads`](/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 the agent's steps: `agent_trace` (a readable log of plan, searches, screening, and analysis) and `agent_trace_raw`. 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[].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. |
| `interactions[].stats` | Papers `retrieved`, `eligible`, and `included` in the answer. |
| `interactions[].step_count` | How many agent steps have run so far. |

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.