# Deep Research

Deep Research gives your AI assistant the ability to launch multi-round, multi-source research investigations and produce synthesised, cited markdown reports. Unlike one-shot [Web Search](/docs/documentation/system-tools/web-search), it plans sub-queries, fetches and re-ranks sources, follows promising links, reflects between rounds, and stitches the evidence into a final report.

Use Deep Research when the user asks for a thorough investigation, a comparison across many sources, a literature review, or anything that benefits from following citations across pages. Use [Web Search](/docs/documentation/system-tools/web-search) for quick fact lookups where sub-15s latency matters.

## Enabling Deep Research

Enable the tool on an assistant:


```json
{
  "name": "Research Assistant",
  "instructions": "You are a thorough research assistant.",
  "model": "ftg-3.0",
  "tools": [{"type": "deep_research"}]
}
```

The assistant must have the `use_deep_research` capability granted to its callers, and the organisation must have a positive Deep Research budget.

## Tool Modes

| Mode | Behaviour | Typical runtime | Output |
|  --- | --- | --- | --- |
| `fast` | Single round, top results re-ranked + cited inline | ~10 – 15s | Inline cited summary returned in the same response |
| `deep` | Multi-round, link-following, reflection between rounds, final synthesis | 2 – 10 min | Background session id; final report fetched from `/v1/research/sessions/{id}/result` |


The default mode is configured per assistant. The model can override it at call time when `allow_mode_selection` is enabled.

## Tool Arguments

| Argument | Type | Required | Description |
|  --- | --- | --- | --- |
| `query` | string | yes | The research topic in natural language. The planner expands this into sub-queries. |
| `mode` | `"fast"` | `"deep"` | no | Override the assistant's default mode. |
| `research_loop_model` | string | no | FTG-series model override for the research loop (e.g. `ftg-3.0`, `ftg-3.0-speed`). |
| `rounds_max` | integer (1 – 10) | no | Cap rounds for deep mode. Clamped to org policy max. |
| `enabled_providers` | array of strings | no | Override which search providers to use. |


## How It Works

When the model invokes `deep_research`:

1. **Plan** — the planner generates a persona and a set of sub-queries.
2. **Search** — every enabled search provider is called in parallel.
3. **Fetch** — top results are scraped and parsed.
4. **Re-rank** — a cross-encoder scores evidence against the original query.
5. **Reflect** (deep mode) — gaps are detected and a follow-up round is planned.
6. **Synthesise** — the LLM produces a markdown report with inline `[1]`, `[2]` citations.


## Fast Mode Response


```json
{
  "type": "tool_call_result",
  "tool_name": "deep_research",
  "result": {
    "report_markdown": "FastAPI is a modern, high-performance web framework... [1]",
    "citations": [
      {"index": 1, "url": "https://fastapi.tiangolo.com/", "title": "FastAPI"}
    ],
    "session_id": "rsess_abc123"
  }
}
```

## Deep Mode Response

Deep mode returns a session id immediately. The assistant streams progress and fetches the final report:


```json
{
  "type": "tool_call_result",
  "tool_name": "deep_research",
  "result": {
    "session_id": "rsess_xyz789",
    "status": "running",
    "stream_url": "/v1/research/sessions/rsess_xyz789/stream",
    "result_url": "/v1/research/sessions/rsess_xyz789/result"
  }
}
```

Stream progress events from `stream_url` and fetch the final report from `result_url` once `status` is `done`.

## Cost & Billing

Deep Research metered usage is billed via the `/v1/research/usage` endpoint:

- Search-provider calls — per call (free for Wikipedia / arXiv).
- Page scraping — per second of compute.
- LLM tokens — per token, resolved against the configured FTG model.
- Re-ranker — per second of compute.


Every cost row is stamped with a margin and surfaced in the customer-facing total. A pre-flight budget guard refuses sessions before any work runs if the org is already over its cap.

## Use Cases

- **Comparative analysis** — Compare hotels, products, or services across many sources.
- **Literature reviews** — Aggregate the state of an academic topic with citations.
- **Market scans** — Gather and synthesise current pricing or feature data across vendors.
- **Brief generation** — Produce a structured research brief on a topic ahead of a meeting.


## Related Resources

- [Web Search](/docs/documentation/system-tools/web-search) — Quick lookup for single facts and current events.
- [System Tools Overview](/docs/documentation/system-tools) — All available built-in tools.
- [Assistants](/docs/documentation/core-concepts/assistants) — Configuring tools on an assistant.
- [Create Research Session](/assets/create-session.32a428759325814b3a301d8cb84e265e166ed95c1f7ef470012f029be96cc896.79a4f7ef.md) — REST API equivalent.
- [Stream Research Events](/assets/stream-events.2463096b5ec9957aa90b2b706f6309530b612196a2afe7bfcdc9b910609ebd71.79a4f7ef.md) — Subscribe to live progress.
- [Get Research Result](/assets/get-result.696c7991321b5617e0f826524e65ad762bc57c008ce733aaf376cb35557eea43.79a4f7ef.md) — Fetch the final report.