When a Simple Search Isn't Enough: Building With the Research API

A developer guide to the You.com Research API. Multi-step search, synthesis, and cited answers.

When a Simple Search Isn't Enough

You've used the You.com 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 queries need more than a list of links returned. When your app or agent needs to answer questions like "what are the latest breakthroughs in quantum computing" or "compare mRNA vaccine platforms," it needs to search across dozens of sources, cross reference them, and synthesize a coherent answer with citations.

That's what the You.com Research API does. It searches, reads, and synthesizes multiple sources into a cited markdown answer you can plug directly into your app or agent workflow.

What You'll Build

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

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

Search API returns raw results:

[
	{ "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, cited answer:

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

And you don't have to build any of the machinery behind it. No search orchestration, no page extraction, no citation tracking. One API call, one cited answer.

Why This Approach

If you've tried building a multi-step research workflow yourself, you know how much work goes into it. Getting the search right is just the start. You also need to read and extract content from pages, figure out when you have enough information, synthesize it all into something coherent, and create accurate citations back to your sources. It adds up fast.

The Research API handles all of that. You send a question, pick an effort level, and get back a cited markdown answer. The search strategy, source selection, synthesis, and citation creation are fully managed. You skip the hardest parts of the problem and get output that's been benchmarked against industry standard evaluations.

What the Research API Does Under the Hood

The Research API is powered by a You.com own 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. For example, 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.

‍When to Use Research Versus Search

The core tradeoff is latency versus depth. Search is fast, great when you need raw results or want full control over how you process them. Research takes longer, but you get a synthesized, cited answer without building any of the orchestration yourself.

That orchestration is the part most teams underestimate. Managing iterative search loops, extracting clean content from web pages, tracking citations across dozens of sources, and deciding when you have enough information to write a good answer. The Research API does all of this for you, and it's been tested extensively. It ranks #1 on DeepSearchQA with 83.67% accuracy and 93.16% F1, and posts top results on SimpleQA, FRAMES, and BrowseComp with a fraction of the latency of comparable offerings.

For proven accuracy out of the box, Research is the faster path. You can read more about our evaluation methodology in our evals whitepaper.

Pick Search when your application needs links. Pick Research when it needs answers.

Prerequisites

You need two things:

1. A You.com API key. Get one at you.com/platform
2. The SDK for your language:

## Python
pip install youdotcom

# TypeScript
npm install @youdotcom-oss/sdk

‍That's it. No other dependencies needed.

Step-by-Step Walkthrough

Python

1. Set your API key

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

2. Make a research call

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.

3. Print the sources

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

‍4. Try different effort levels

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)

‍TypeScript

1. Install and initialize

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

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

2. Make a research call

  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

‍3. 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:

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);
}

‍Full Working Example

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

• GitHub: youdotcom-oss/ydc-research-sample

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:

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

# 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, more thorough analysis.

Choosing the Right Effort Level

• lite for quick factual queries where you want a synthesized answer rather than raw results
• 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 your application requires maximum source coverage and depth

Response Format

The API returns a structured response:‍

{
  "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. Full API docs with all parameters and response fields
• 10 Creative Ways to Use AI Web Search & Research in Your n8n Workflows. Automate research with n8n workflows
• 10 Creative Ways to Use AI Web Search in Your LangChain Apps. Integrate with LangChain for agent-powered research
• Simple Search Sample. If you need raw search results instead
• Full API Docs. Documentation for all You.com APIs
• Get an API Key. Sign up and start building

Resources

• Research API Reference
• Python SDK (pip install youdotcom)
• TypeScript SDK (npm install @youdotcom-oss/sdk)
• GitHub: ydc-research-sample
• Discord