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, relevant snippets, and full-page content.

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.

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

The text that comes back with each result depends on the extraction parameter:

Our classification system determines when to include news results based on query intent. Set knowledge: "core" to also request licensed-data results in results.knowledge.

What You Get

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

Web results

• Relevant web pages from across the internet
• Multiple text snippets per result for context (replaced by highlights when you ask for them)
• Publication dates
• Thumbnail images and favicons for UI display

News results (when relevant)

• Recent news articles from authoritative sources
• Article summaries and headlines
• Publication timestamps for freshness
• Associated 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
  }
}

All results are returned in clean, structured JSON requiring no HTML parsing or post-processing.

Features

Each result can carry three levels of text. The right one depends on whether a person or a model is reading it.

See Retrieve page content for highlights vs. full page, extraction_source, crawl timeout, and the Contents API comparison.

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 search snippets to provide context to your LLM without hallucination. The structured snippets are ready to feed into a prompt. For token-sensitive pipelines, request highlights instead.

from youdotcom import You
you = You()
def get_context(query):
    res = you.search(query=query, count=5)
    snippets = []
    if res.results and res.results.web:
        for result in res.results.web:
            if result.snippets:
                snippets.extend(result.snippets)
    return "\n".join(snippets)
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}"

AI agent knowledge retrieval

Give AI agents access to real-time web information—up-to-date facts, news, or specialized domain knowledge.

News monitoring & alerts

Track breaking news, competitor mentions, or industry trends. Classification includes news results when they are relevant. See News Results.

Content research & analysis

Gather information from multiple sources for content creation, competitive intelligence, or market research.

Knowledge base construction

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

Best Practices

1. Use highlights for RAG

Request extraction_mode: "highlights" and read contents.highlights. You get the passages most relevant to your query, already sized for a prompt, without paying to crawl and process whole pages. Fall back to the snippets array when you are rendering results for a person rather than grounding a model.

2. Implement caching

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

3. 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()

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

5. 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 snippets 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