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

1
from youdotcom import You
2
3
with You(api_key_auth="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])

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
}

1
from youdotcom import You
2
from youdotcom.models import LiveCrawl, LiveCrawlFormats
3
4
with You(api_key_auth="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])

1
from youdotcom import You
2
from youdotcom.models import ContentsFormats
3
4
with You(api_key_auth="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)

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
]

1
from youdotcom import You
2
from youdotcom.models import ResearchEffort
3
4
you = You(api_key_auth="api_key")
5
6
res = you.research(
7
    input="What are the tradeoffs between microservices and monolithic architectures for high-traffic applications?",
8
    research_effort=ResearchEffort.STANDARD,
9
)
10
11
print(res.output.content[:500])
12
print(f"\nSources: {len(res.output.sources)}")
13
for source in res.output.sources:
14
    print(f"  - {source.title or 'Untitled'}: {source.url}")

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
}

1
curl -X POST https://api.you.com/v1/research \
2
  -H "X-API-Key: api_key" \
3
  -H "Content-Type: application/json" \
4
  -d '{
5
    "input": "List the top three cloud providers and give a one-line summary for each.",
6
    "research_effort": "standard",
7
    "source_control": {
8
      "freshness": "year"
9
    },
10
    "output_schema": {
11
      "type": "object",
12
      "properties": {
13
        "providers": {
14
          "type": "array",
15
          "items": {
16
            "type": "object",
17
            "properties": {
18
              "name": { "type": "string" },
19
              "summary": { "type": "string" }
20
            },
21
            "required": ["name", "summary"],
22
            "additionalProperties": false
23
          }
24
        }
25
      },
26
      "required": ["providers"],
27
      "additionalProperties": false
28
    }
29
  }'

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

Try in Postman

Fork one of our pre-built collections, add your API key to the production environment, and send your first request without writing any code.

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, you.com/docs/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:

1
"docs.you.com": {
2
  "name": "you.com/docs",
3
  "url": "https://you.com/docs/_mcp/server",
4
  "headers": {}
5
}

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

Use cases

Ready-to-run sample apps built on You.com APIs. Each comes with a live demo and a fully forkable open-source GitHub repo — clone it, extend it, or use it as a starting point for your own project.

Pricing

You.com uses pay-as-you-go pricing based on the API and usage. All new accounts include $100 in free credits.

Quick pricing overview

• Search API: $5.00 per 1,000 calls (up to 100 results per call)
• Search API livecrawl add-on: $1.00 per 1,000 pages
• Contents API: $1.00 per 1,000 pages
• Research API: Starts at $12 per 1,000 calls (varies per effort tier)

Track your usage and spending from the analytics dashboard. For volume discounts, annual pricing, and enterprise features, visit you.com/pricing or contact [email protected].