Web Search API Overview

What Is the You.com Web Search API?

The You.com Web Search API delivers high-quality, structured web and news results optimized for programmatic access in AI applications. Designed for developers building RAG systems, AI agents, knowledge bases, and data-driven applications, our Web Search API returns clean, structured data with rich metadata—snippets by default, query-relevant highlights or full-page content on request.

If the job is a cited answer rather than raw results, or you already have URLs, Choose the Right API maps those jobs to the Answer API, Research API, Contents API, and Finance Research API.

Endpoints

Each API has its own endpoint. Every request sends your API key in the X-API-Key header, except Inference Router requests, which send it as Authorization: Bearer.

The Inference Router, Answer, Research, and Finance Research APIs run only on api.you.com. Sending one of those paths to ydc-index.io returns 403 with {"message": "Missing Authentication Token"}, even when the key is valid.

How It Works

The Web Search API processes your query and returns unified results from both web and news sources in a single request. Every result carries core information—URL, title, and description—and rich metadata such as publication dates, thumbnails, and favicons.

Pick the text level that matches your reader:

Raw POST /v1/search returns snippets when you omit extraction. you.search() in the Python SDK 3.6.0 and later sends highlights and knowledge="core" when you omit both arguments. The Web Search API Quickstart shows knowledge=None and extraction=None for snippets.

When the question needs a live fact rather than passages—a price, a metric, a forecast—add knowledge: "core" for licensed data in results.knowledge. Knowledge covers what it returns.

Our classification system determines when to include news results based on query intent.

What You Get

Every search returns structured JSON with two main result types, plus knowledge results when you ask for them:

Web results

• Text per result—snippets by default, contents.highlights with extraction_mode: "highlights"
• Publication dates
• Thumbnail images and favicons for UI display

News results (when relevant)

• Recent news articles from authoritative sources
• Publication timestamps, images, and metadata
• Full article content (HTML or Markdown) via full page extraction

Knowledge results (when knowledge: "core" and the query matches)

• Licensed-data answers with provider attribution
• Omitted from the response when none are relevant

{
  "results": {
    "web": [
      {
        "url": "https://example.com/article",
        "title": "Article Title",
        "description": "Brief description of the content",
        "snippets": [
          "Relevant excerpt from the page",
          "Another relevant passage"
        ],
        "thumbnail_url": "https://example.com/image.jpg",
        "page_age": "2025-11-15T10:30:00",
        "favicon_url": "https://example.com/favicon.ico"
      }
    ],
    "news": [
      {
        "title": "Breaking News Article",
        "description": "News article summary",
        "url": "https://news.com/article",
        "page_age": "2025-11-15T14:00:00",
        "thumbnail_url": "https://news.com/image.jpg"
      }
    ]
  },
  "metadata": {
    "search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90",
    "query": "your search query",
    "latency": 0.342
  }
}

Features

If you already have URLs and do not need to search first, use the Contents API.

Parameters

View full API reference

Send parameters as a JSON body on POST /v1/search. Array fields are plain JSON arrays.

Common Use Cases

RAG (Retrieval-Augmented Generation)

Use highlights to provide context to your LLM without hallucination. Request extraction_mode: "highlights" and read contents.highlights—the structured passages are ready to feed into a prompt. For search UIs that render results for a person, the default snippets array is the lighter fit.

from youdotcom import You
from youdotcom.models import Extraction, ExtractionMode
you = You()
def get_context(query):
    res = you.search(
        query=query,
        count=5,
        extraction=Extraction(extraction_mode=ExtractionMode.HIGHLIGHTS),
    )
    highlights = []
    if res.results and res.results.web:
        for result in res.results.web:
            if result.contents and result.contents.highlights:
                highlights.extend(result.contents.highlights)
    return "\n".join(highlights)
user_question = "What is the current state of quantum computing?"
context = get_context(user_question)
prompt = f"Based on this information:\n{context}\n\nAnswer: {user_question}"

News monitoring & alerts

Track breaking news, competitor mentions, or industry trends. See News Results.

Knowledge base construction

Use full page extraction to build knowledge bases with full-page content in clean Markdown.

Best Practices

1. Implement caching

Cache frequent queries to reduce API calls and improve response times. Consider a 5-15 minute TTL for most use cases.

2. Handle empty results

Always check if results.web or results.news arrays are empty before processing:

if res.results and res.results.web:
    for result in res.results.web:
        process(result)
else:
    handle_no_results()

3. Use appropriate count values

• For RAG: count=5-10 is usually sufficient
• For UI display: count=20-50 for pagination
• For data gathering: count=100 (max) for comprehensive coverage

4. Use search operators and query parameters

Use search operators and request controls to reduce noise and get more relevant results.

Pricing

$5.00 per 1,000 calls (up to 100 results per call)

See the Billing page for complete pricing details.

Agents can also pay per call without an account. GET /v1/search and both verbs of /v1/agents/search accept machine payments, settling each request in USDC from a funded wallet instead of drawing down credits.

What’s included:

• Web and news results in a single unified request
• Up to 100 results per call
• News results at no extra cost
• Knowledge results from licensed data providers at no extra cost
• LLM-ready text excerpts with rich metadata
• Country, language, recency, domain and more targeting filters

Full page extraction add-on—$1.00 per 1,000 pages fetched live

Full page content via extraction_mode: "full_page" (HTML, Markdown, or both) is billed separately from the base Web Search API rate. Only pages crawled live are billed, so what you pay depends on extraction_source: fetch crawls every result, blend (the default) charges only for the pages it could not serve from cache, and cache adds no extraction charge at all.

Example: A single call with count=10 and extraction_mode: "full_page" returns 10 web results and 10 news results—20 pages total. This call leaves extraction_source unset, so it runs blend. Say 2 of the 20 pages are already cached and the other 18 are crawled live.

Cache coverage varies by query, so treat that split as one outcome rather than a rate to budget against. This call costs $0.025 when all 20 pages are crawled live and $0.005 with extraction_source: "cache". See Billing for the full breakdown.

For volume discounts, annual pricing, or enterprise features, visit you.com/pricing or contact api@you.com.

Data Retention

Organizations operating under strict privacy, compliance, or security mandates can add Zero Data Retention (ZDR) to an enterprise agreement. ZDR restricts retention of Web Search API request and response content account-wide and requires no changes to your integration. See Zero Data Retention for what it covers and how to enable it.

FAQ

Next Steps