You.com Web Search API Quickstart

The Web Search API returns real-time web and news results as structured, LLM-ready JSON. Feed the results into your prompt to ground a model in fresh information.

Get an API key at you.com/platform. The samples below read YDC_API_KEY. See the site Quickstart for the five-API tour and API key management for best practices.

from youdotcom import You
with You() as you:
    results = you.search(query="global birth rate trends", count=5)
    for result in results.results.web:
        print(result.title)
        print(result.url)
        highlights = result.contents.highlights if result.contents else None
        if highlights:
            print(highlights[0])

The Python sample follows the SDK default and prints contents.highlights. The TypeScript and curl calls omit extraction, so raw POST /v1/search returns snippets. you.search() in the Python SDK 3.6.0 and later sends knowledge="core" and extraction={"extraction_mode": "highlights"} when you pass neither argument, and snippets is None. Knowledge adds no extra charge. See Billing.

Pass both arguments as None for snippets:

results = you.search(
    query="global birth rate trends",
    count=5,
    knowledge=None,
    extraction=None,
)

Highlights accepts count up to 50. The SDK default uses highlights, so a count above 50 needs extraction=None or extraction_mode set to full_page.

A raw POST /v1/search call returns JSON like this:

{
  "results": {
    "web": [
      {
        "url": "https://www.worldbank.org/en/topic/population",
        "title": "Population | World Bank",
        "description": "The World Bank tracks global birth rate and population trends.",
        "snippets": [
          "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."
        ],
        "page_age": "2025-10-01T00:00:00",
        "favicon_url": "https://ydc-index.io/favicon?domain=worldbank.org&size=128"
      }
    ]
  },
  "metadata": {
    "query": "global birth rate trends",
    "search_uuid": "a1b2c3d4-0000-0000-0000-000000000000",
    "latency": 0.38
  }
}

TypeScript, MCP, or the Python SDK

TypeScript and JavaScript have three paths. Use fetch against the REST APIs when the application needs the JSON. Use @youdotcom-oss/mcp, or the hosted server at https://api.you.com/mcp, when an agent should call the tools. Use the Python SDK when you want a typed client that tracks new API fields. The @youdotcom-oss/sdk package is deprecated.

Add Highlights

Snippets are the HTTP default. Raw POST /v1/search returns them when the body omits extraction. The Python SDK 3.6.0 and later defaults to highlights and knowledge="core", so you.search() returns contents.highlights and snippets is None. Pass knowledge=None and extraction=None for snippets. The sample sets extraction_mode to highlights, which is what an HTTP client sends for the same excerpts.

from youdotcom import You
from youdotcom.models import Extraction, ExtractionMode
with You() as you:
    results = you.search(
        query="global birth rate trends",
        count=5,
        extraction=Extraction(
            extraction_mode=ExtractionMode.HIGHLIGHTS,
        ),
    )
    if results.results and results.results.web:
        for result in results.results.web:
            if result.contents and result.contents.highlights:
                print(result.title)
                print(result.contents.highlights[0])

Add Full Page Content

Use extraction with extraction_mode: "full_page" to attach clean Markdown or HTML for each result. See Retrieve page content for highlights, cache vs. live crawl, and pricing.

from youdotcom import You
from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode
with You() as you:
    results = you.search(
        query="global birth rate trends",
        count=5,
        extraction=Extraction(
            extraction_mode=ExtractionMode.FULL_PAGE,
            full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]},
        ),
    )
    for result in results.results.web:
        if result.contents and result.contents.markdown:
            print(result.title)
            print(result.contents.markdown[:400])

Try in Postman

Fork the Web Search API collection, add your API key to the production environment, and hit Send.

Next Steps

Web Search API Overview

How the API works, what you get, pricing, and when to use each feature

Retrieve page content

Highlights vs. full page content, extraction source, and crawl timeout

API reference

Full parameter reference, request/response schemas, and playground

Site Quickstart

Try Inference Router, Answer, Contents, Research, and Finance Research in one tour