***

## title: Research

<DemoPreview href="https://you.com/examples/research" thumbnailUrl="https://cdn.you.com/img/docs/ResearchTemplateThumbnail.png" thumbnailDarkUrl="https://cdn.you.com/img/docs/ResearchTemplateThumbnailDark.png" />

## When a Simple Search Isn't Enough

You've used the Search API. You send a query, you get back a list of web results. Titles, URLs, snippets. It works great for quick lookups, building search UIs, and feeding results into RAG pipelines.

But some questions need more than a list of links. Questions like "what are the latest breakthroughs in quantum computing" or "how do mRNA vaccines work" need someone (or something) to actually read through dozens of sources, cross-reference them, and write up a coherent answer with citations.

That's what the Research API does. It's like having a research assistant that reads the web and writes you a report with footnotes.

***

## What You'll Build

By the end of this guide you'll be able to call the Research API in Python or TypeScript and get back comprehensive, cited answers to  questions of varying complexity.

Here's the difference between Search and Research for the same query:

**Search API** returns raw results:

```json
[
  { "title": "Google Quantum AI: Willow Chip", 
    "url": "https://blog.google/...", 
    "snippet": "Google's Willow chip demonstrated..."
  },
  { "title": "IBM Quantum: Heron Processor", 
    "url": "https://www.ibm.com/...", 
    "snippet": "IBM announced..."
  }
]
```

**Research API** returns a synthesized, grounded answer with inline citations:

```markdown
## Recent Breakthroughs in Quantum Computing

Quantum computing has seen several major advances in recent years...

**Error correction milestones.** Google's Willow chip demonstrated that
increasing the number of qubits can actually reduce errors [1], a key
threshold for practical quantum computing...

**Hardware scaling.** IBM's Heron processor achieved... [2]

Sources:
[1] Google Quantum AI: Willow Chip
    https://blog.google/technology/research/google-willow-quantum-chip/
[2] IBM Quantum: Heron Processor
    https://www.ibm.com/quantum/blog/ibm-quantum-heron
```

Same question, fundamentally different output. Search gives you building blocks. Research gives you the finished product.

***

## Why This Approach

### What the Research API Does Under the Hood

The Research API doesn't just run one search. It's powered by the You.com search index, purpose-built for speed, accuracy, and relevance. Instead of relying on third-party search providers, the Research API searches and reads pages directly from this index. That means lower latency, fresher results, and better extraction quality than you'd get stitching together external services yourself.

On top of that index sits an agentic system that does the actual research. It doesn't follow a fixed pipeline. Instead it works in an iterative loop:

1. Reads your question and decides what to search for
2. Searches the web and reviews the results
3. Visits promising pages and extracts the relevant content
4. Decides whether to search again, visit more pages, or start writing based on what it's found so far
5. Repeats until it has enough information (controlled by the effort level you choose)
6. Synthesizes everything into a cited markdown answer

The agent adapts its research strategy as it goes. A question about quantum computing might lead it down a different path than one about financial regulations. Higher effort levels give the agent more time to iterate, which means more searches, more pages read, and a more thorough answer.

Because the search index, page extraction, and synthesis are all built and optimized together, the Research API can deliver results that would be difficult to replicate by chaining separate tools.

```mermaid
flowchart LR
    A["Your Question"] --> B["Research Agent"]
    B --> C["Search the Web"]
    C --> D["Read Pages"]
    D --> E{"Enough Info?"}
    E -- "No" --> C
    E -- "Yes" --> F["Synthesize + Cite"]
    F --> G["Cited Markdown Answer<br />+ Source List"]
    style A fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f
    style B fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#1e3a5f
    style E fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#1e3a5f
    style G fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#1e3a5f
```

### When to Use Research vs Search

|              | **Search API**                               | **Research API**                                        |
| ------------ | -------------------------------------------- | ------------------------------------------------------- |
| **Speed**    | Fast (\~1s)                                  | Slower (5–60s depending on effort)                      |
| **Output**   | List of web results (title, URL, snippet)    | Comprehensive markdown answer with citations            |
| **Best for** | Quick lookups, search UIs, and RAG pipelines | Complex questions, report generation, and deep analysis |
| **Example**  | "nextjs docs"                                | "how does next.js compare to remix for production apps" |

**Use Research when:**

* The question requires reading and synthesizing multiple sources
* You need a cited, comprehensive answer (not just links)
* You're building report generation, fact-checking, or deep analysis features
* Your users expect a written answer, not a list of results

**Use Search when:**

* You need raw results fast
* You're building a search UI or autocomplete
* You're feeding results into your own RAG pipeline
* You need fine-grained control over result filtering (freshness, country, language, livecrawl etc.)

***

## Prerequisites

You need two things:

1. **A [You.com](http://You.com) API key.** Get one at [you.com/platform](http://you.com/platform)
2. **The SDK** for your language:

```bash
# Python
pip install youdotcom

# TypeScript
npm install @youdotcom-oss/sdk
```

That's it. No other dependencies needed.

***

## Step-by-Step Walkthrough

### Python

<Steps>
  ### Set your API key

  ```bash
  export YDC_API_KEY="your-api-key-here"
  ```

  ### Make a research call

  ```python
  import os
  from youdotcom import You

  you = You(api_key_auth=os.environ["YDC_API_KEY"])
  response = you.research(input="What are the latest breakthroughs in quantum computing?")
  print(response.output.content)
  ```

  `response.output.content` is a markdown string with inline citations like \[1], \[2]. `response.output.sources` is the list of sources used.

  ### Print the sources

  ```python
  for i, source in enumerate(response.output.sources, 1):
      print(f"[{i}] {source.title}")
      print(f"    {source.url}")
  ```

  ### Try different effort levels

  ```python
  import os
  from youdotcom import You, models

  you = You(api_key_auth=os.environ["YDC_API_KEY"])

  # Quick answer (~5s)
  response = you.research(input="what is RAG", research_effort=models.ResearchEffort.LITE)

  # Thorough research (~20-30s)
  response = you.research(input="compare RAG architectures", research_effort=models.ResearchEffort.DEEP)

  # Most comprehensive (~30-60s)
  response = you.research(input="full analysis of RAG vs fine-tuning", research_effort=models.ResearchEffort.EXHAUSTIVE)
  ```
</Steps>

### TypeScript

<Steps>
  ### Install and initialize

  ```tsx
  import { You } from "@youdotcom-oss/sdk";

  const you = new You({ apiKeyAuth: process.env.YDC_API_KEY });
  ```

  ### Make a research call

  ```tsx
  const result = await you.research({
    input: "What are the latest breakthroughs in quantum computing?",
    researchEffort: "standard",
  });

  console.log(result.output.content);     // markdown answer
  console.log(result.output.sources);     // source list
  ```

  ### Use in a Next.js API route

  This is the pattern used in the live demo. The API route calls Research server-side so the API key stays safe:

  ```tsx
  import { NextResponse } from "next/server";
  import { You } from "@youdotcom-oss/sdk";

  export const maxDuration = 60; // Research can take up to 60s

  export async function POST(request: Request) {
    const { input, research_effort } = await request.json();
    const you = new You({ apiKeyAuth: process.env.YDC_API_KEY });
    const result = await you.research({ input, researchEffort: research_effort });
    return NextResponse.json(result);
  }
  ```
</Steps>

***

## Full Working Example

We've built a complete sample app you can fork and deploy:

* **GitHub:** [youdotcom-oss/ydc-research-sample](https://github.com/youdotcom-oss/ydc-research-sample)
* **Live demo:** [ydc-research-sample.vercel.app](http://ydc-research-sample.vercel.app)

The repo includes:

* `research.py` is a standalone Python CLI script
* `app/api/research/route.ts` is the Next.js API route using the TypeScript SDK
* `app/page.tsx` is the React frontend with effort level picker and markdown rendering

To run it yourself:

```bash
git clone https://github.com/youdotcom-oss/ydc-research-sample.git
cd ydc-research-sample

# Python
pip install youdotcom
export YDC_API_KEY="your-key"
python research.py "your question here"

# Web app
cp .env.example .env.local   # add your API key
npm install
npm run dev                   # open localhost:3000
```

***

## Customization Guide

### Effort Levels

The `research_effort` parameter controls how deep the Research API digs. Higher effort means more searches, more sources read, and more thorough analysis.

| **Level**    | **Speed** | **When to Use**                                                                         |
| ------------ | --------- | --------------------------------------------------------------------------------------- |
| `lite`       | \~5s      | Quick factual questions, simple lookups that still benefit from synthesis               |
| `standard`   | \~10–15s  | Default. Balanced speed and depth. Good for most questions                              |
| `deep`       | \~20–30s  | Complex topics that need cross-referencing. Competitive analysis, technical comparisons |
| `exhaustive` | \~30–60s  | Maximum depth. Due diligence, comprehensive reports, academic-style research            |

### Choosing the Right Effort Level

* **`lite`** for anything you'd normally just google but want a synthesized answer instead of clicking through links
* **`standard`** when you're not sure. It's the sweet spot for most use cases
* **`deep`** when accuracy and thoroughness matter more than speed
* **`exhaustive`** when you need to be really sure. Compliance checks, investment research, technical deep dives

### Response Format

The API returns a structured response:

```json
{
  "output": {
    "content": "## Quantum Computing Breakthroughs\n\nQuantum computing has seen several major advances... [1]\n\n...",
    "content_type": "text",
    "sources": [
      {
        "url": "https://blog.google/technology/research/google-willow-quantum-chip/",
        "title": "Google Quantum AI: Willow Chip",
        "snippets": ["Google's Willow chip demonstrated..."]
      }
    ]
  }
}
```

* `output.content` is a markdown string with numbered inline citations (\[1], \[2], etc.)
* `output.sources` is an array of sources, each with URL, title, and relevant snippets
* Citations in the content map to the sources array by index

***

## What's Next

Now that you can call the Research API, here are some directions to explore:

* [**Research API Reference**](https://docs.you.com/api-reference/research/v1-research). Full API docs with all parameters and response fields.
* [**10 Creative Ways to Use AI Web Search & Research in Your n8n Workflows**](https://you.com/resources/10-ways-to-use-ai-web-search-research-in-n8n-workflows). Automate research with n8n workflows.
* [**Simple Search Sample**](https://github.com/youdotcom-oss/ydc-simple-search-sample). If you need raw search results instead.
* [**Full API Docs**](https://docs.you.com). Documentation for all [You.com](http://You.com) APIs.
* [**Get an API Key**](https://you.com/platform). Sign up and start building.

***

## Resources

* [Research API Reference](https://docs.you.com/api-reference/research/v1-research)
* [Python SDK](https://pypi.org/project/youdotcom/) (`pip install youdotcom`)
* [TypeScript SDK](https://www.npmjs.com/package/@youdotcom-oss/sdk) (`npm install @youdotcom-oss/sdk`)
* [GitHub: ydc-research-sample](https://github.com/youdotcom-oss/ydc-research-sample)
* [Live Demo](https://ydc-research-sample.vercel.app/)
* [Discord](https://discord.com/invite/youdotcom/)