Quickstart

You.com gives you real-time web intelligence through three core APIs: Search, Contents, and Research. This quickstart will get you searching the web and answering questions within minutes. Then, we’ll show you how to evaluate us.

What You.com offers

Step 1: Get your API key

Sign in or create an account, then get an API key here: https://you.com/platform/api-keys. You’ll start with $100 in complimentary credits — no credit card required.

Step 2: Try the Search API

The Search API takes a natural language query and returns structured web and news results.

1
from youdotcom import You
2
3
with You(api_key_auth="YDC_API_KEY") as you:
4
    results = you.search.unified(query="global birth rate trends", count=5)
5
6
    for result in results.results.web:
7
        print(result.title)
8
        print(result.url)
9
        if result.snippets:
10
            print(result.snippets[0])

You’ll get back structured JSON like this:

1
{
2
  "results": {
3
    "web": [
4
      {
5
        "url": "https://www.worldbank.org/en/topic/population",
6
        "title": "Population | World Bank",
7
        "description": "The World Bank tracks global birth rate and population trends.",
8
        "snippets": [
9
          "Global fertility rates have declined significantly over the past five decades, falling from an average of 5 births per woman in 1960 to around 2.3 today."
10
        ],
11
        "page_age": "2025-10-01T00:00:00",
12
        "authors": [],
13
        "favicon_url": "https://ydc-index.io/favicon?domain=worldbank.org&size=128"
14
      }
15
    ]
16
  },
17
  "metadata": {
18
    "query": "global birth rate trends",
19
    "search_uuid": "a1b2c3d4-0000-0000-0000-000000000000",
20
    "latency": 0.38
21
  }
22
}

Improve accuracy with livecrawl

Search results already include snippets — short, query-relevant text extracts from target pages. Use the livecrawl parameter to fetch full page content for each result as clean Markdown or HTML.

This will naturally increase latency, but massively improves knowledge accuracy.

1
from youdotcom import You
2
from youdotcom.models import LiveCrawl, LiveCrawlFormats
3
4
with You(api_key_auth="YDC_API_KEY") as you:
5
    results = you.search.unified(
6
        query="global birth rate trends",
7
        count=5,
8
        livecrawl=LiveCrawl.ALL,
9
        livecrawl_formats=LiveCrawlFormats.MARKDOWN,
10
    )
11
12
    for result in results.results.web:
13
        if result.contents:
14
            print(result.title)
15
            print(result.contents.markdown[:400])

Results that support live crawling will include a contents.markdown field with the full page. For RAG pipelines that need deep context rather than surface-level snippets, this is the parameter to reach for.

Full Search API reference and all parameters

Step 3: Try the Contents API

The Contents API fetches content from URLs you specify, either as raw HTML, Markdown or both.

1
from youdotcom import You
2
from youdotcom.models import ContentsFormats
3
4
with You(api_key_auth="YDC_API_KEY") as you:
5
    pages = you.contents.generate(
6
        urls=[
7
            "https://competitor-a.com/pricing",
8
            "https://competitor-b.com/pricing",
9
        ],
10
        formats=[ContentsFormats.MARKDOWN],
11
    )
12
13
    for page in pages:
14
        print(f"=== {page.title} ===")
15
        print(page.markdown)

Each URL comes back as a structured object:

1
[
2
  {
3
    "url": "https://competitor-a.com/pricing",
4
    "title": "Pricing — Competitor A",
5
    "markdown": "# Pricing\n\n## Starter\n$49/month...",
6
    "metadata": {
7
      "site_name": "Competitor A",
8
      "favicon_url": "https://ydc-index.io/favicon?domain=competitor-a.com&size=128"
9
    }
10
  }
11
]

Full Contents API reference and all parameters

Step 4: Try the Research API

The Research API goes beyond a single web search. Give it a complex question and it runs multiple searches, reads through the sources, and synthesizes a thorough, citation-backed answer.

1
import requests
2
3
response = requests.post(
4
    "https://api.you.com/v1/research",
5
    headers={
6
        "X-API-Key": "YOUR_API_KEY",
7
        "Content-Type": "application/json",
8
    },
9
    json={
10
        "input": "What are the tradeoffs between microservices and monolithic architectures for high-traffic applications?",
11
        "research_effort": "standard",
12
    },
13
)
14
15
data = response.json()
16
print(data["output"]["content"][:500])
17
print(f"\nSources: {len(data['output']['sources'])}")
18
for source in data["output"]["sources"]:
19
    print(f"  - {source['title']}: {source['url']}")

The response includes a Markdown-formatted answer with inline citations and the list of sources used:

1
{
2
  "output": {
3
    "content": "## Microservices vs Monolithic Architectures\n\nThe choice between microservices and monolithic architectures involves several key tradeoffs...\n\n### Scalability\nMicroservices allow independent scaling of individual components [[1, 3]]...",
4
    "content_type": "text",
5
    "sources": [
6
      {
7
        "url": "https://example.com/architecture-patterns",
8
        "title": "Architecture Patterns for High-Traffic Systems",
9
        "snippets": [
10
          "Microservices enable teams to scale individual services independently, reducing infrastructure costs for components with uneven load."
11
        ]
12
      }
13
    ]
14
  }
15
}

Use research_effort to control how deep the API digs — lite for quick answers, standard for a good balance, deep or exhaustive when thoroughness matters more than speed.

Full Research API reference and all parameters

More ways to explore

Explore the APIs interactively right here in the docs

• Search API playground
• Contents API playground
• Research API playground

Use the SDKs

Benefit from ergonomic API access, type safety and easy readability.

• Python SDK
• TypeScript SDK

Use a coding agent to write your integration

There are 2 easy ways to create context for your agent:

1. Add /llms-full.txt to any URL path on this site to obtain the full content of a page in plain-text. For example, docs.you.com/llms-full.txt contains complete documentation content including the full text of all pages. This includes the complete API reference, complete with raw OpenAPI specs and SDK code examples.

2. Enable your agent to automatically discover and understand You.com APIs using our documentation-specific MCP server. Simply add the following wherever you store your MCP config:

"docs.you.com": {
  "name": "docs.you.com",
  "url": "https://docs.you.com/_mcp/server",
  "headers": {}
}

Now your agent can automatically search the entirety of the You.com documentation as necessary.

Evaluate You.com

You’re now ready to evaluate. You.com provides an open-source evaluation framework and a trustworthy, reproducible methodology for benchmarking search APIs — so you can measure what actually matters: accuracy, latency, and information retrieval quality.

We’re the only search API provider with peer-reviewed evaluation research. Our methodology was presented at the Association for the Advancement of Artificial Intelligence (AAAI) 2026 conference and received the Best Paper Award — meaning the way we think about search evals has been independently validated by the research community. To read more about our research please read these articles:

1. Stochasticity in Agentic Evaluations: Quantifying Inconsistency with Intraclass Correlation
2. Randomness in AI Benchmarks: What Makes an Eval Trustworthy?

The open-source framework treats each search provider as a sampler: for every query, results are fetched from the API, synthesized into an answer by an LLM, then graded against ground truth. It supports various search providers giving you an apples-to-apples comparison on several benchmarks like:

• SimpleQA — factual question answering
• FRAMES — deep research and multi-hop reasoning
• Latency profiling — end-to-end measurement under real conditions

When starting your own evaluation, keep it simple: run count=10 with no filters on a representative query set, then layer in livecrawl if snippets aren’t providing enough context. The resources below take you further:

• How to Evaluate the Search API — methodology, dataset recommendations (SimpleQA, FRAMES, FreshQA), latency benchmarking, and a production checklist
• Agentic Web Search Playoffs — open-source benchmark comparing web search providers in agentic workflows

Our team can also design and run custom benchmarks tailored to your domain and quality bar. Talk to us

Pricing

Pricing is based on API calls, with additional costs for live crawling. See the full breakdown at you.com/platform/upgrade or reach out to [email protected].