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.

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 intelligent classification system automatically determines when to include news results based on query intent, ensuring you get the most relevant information for your use case.

What You Get

Every search returns structured JSON with two main result types:

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

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

Key Features

Choosing a Content Level

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

Snippets are short, keyword-centered fragments built for a human skimming a results page. They come back by default, with no extraction object.

Highlights upgrade that per-result text to the passages from each page most relevant to your query, sized for token-sensitive agentic workflows. This is the content an agent actually needs, in the response field it already parses. Request them with extraction_mode: "highlights".

Full page content returns the complete page rather than a selection from it. Reach for it when the whole document is the point—archiving, full-text analysis, extracting a table or section that a query-relevant passage would miss, or feeding a long-context model. Request it with extraction_mode: "full_page".

Full page extraction—full page content per result

Add the extraction object to a POST /v1/search request with extraction_mode set to full_page, and every web and news result gains a contents object with the page content. Set extraction.full_page.extraction_formats to ["markdown"] (recommended for LLMs), ["html"], or both.

1
from youdotcom import You
2
from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode
3
4
with You() as you:
5
  # Crawl both web and news results
6
  res = you.search(
7
    query="latest AI developments",
8
    count=5,
9
    extraction=Extraction(
10
      extraction_mode=ExtractionMode.FULL_PAGE,
11
      full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]},
12
    ),
13
  )
14
15
  # Access extracted content from web results
16
  if res.results and res.results.web:
17
      for result in res.results.web:
18
          if result.contents and result.contents.markdown:
19
              print(f"Web: {result.title}")
20
              print(f"Content: {result.contents.markdown[:200]}...\n")
21
22
  # Access extracted content from news results
23
  if res.results and res.results.news:
24
      for result in res.results.news:
25
          if result.contents and result.contents.markdown:
26
              print(f"News: {result.title}")
27
              print(f"Content: {result.contents.markdown[:200]}...\n")

Unified web & news results

Get both web pages and news articles in a single API call. Our classification system automatically determines when to include news results based on query intent.

1
{
2
  "results": {
3
    "web": [ // Web search results
4
      {
5
        "url": "https://example.com/article",
6
        "title": "Article Title",
7
        "description": "Brief description of the content",
8
        "snippets": [
9
          "Relevant excerpt from the page",
10
          "Another relevant passage"
11
        ],
12
        "thumbnail_url": "https://example.com/image.jpg",
13
        "page_age": "2025-11-15T10:30:00",
14
        "favicon_url": "https://example.com/favicon.ico",
15
        "contents": { // Included when extraction_mode is "full_page"
16
          "markdown": "# Article Title\n\nFull page content..."
17
        }
18
      }
19
    ],
20
    "news": [ // News articles (when relevant)
21
      {
22
        "title": "Breaking News Article",
23
        "description": "News article summary",
24
        "url": "https://news.com/article",
25
        "page_age": "2025-11-15T14:00:00",
26
        "thumbnail_url": "https://news.com/image.jpg",
27
        "contents": { // Included when extraction_mode is "full_page"
28
          "markdown": "# Breaking News\n\nFull article content..."
29
        }
30
      }
31
    ]
32
  },
33
  "metadata": {
34
    "search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90",
35
    "query": "your search query",
36
    "latency": 0.342
37
  }
38
}

LLM-optimized output

Every result includes:

• Snippets or highlights: Pre-extracted text excerpts—keyword-centered snippets by default, query-relevant highlights on request
• Descriptions: Clean summaries without HTML clutter
• Metadata: Publication dates, thumbnails, and favicons
• Structured JSON: No parsing required, ready for AI consumption

Advanced search operators

Build powerful and precise search queries using search operators:

• site:domain.com - Search within specific domains
• filetype:pdf - Filter by file type
• +term / -term - Include/exclude specific terms
• Boolean operators: AND, OR, NOT

Learn more about search operators

Global coverage

Target results by geographic region using the country parameter (ISO 3166-1 alpha-2 country codes) and filter by language using the language parameter (BCP 47 language codes).

Freshness controls

Filter results by recency:

• day - Last 24 hours
• week - Last 7 days
• month - Last 30 days
• year - Last 365 days
• YYYY-MM-DDtoYYYY-MM-DD - Custom date range

All optional parameters you can control

View full API reference

Common Use Cases

RAG (Retrieval-Augmented Generation)

Use search snippets to provide context to your LLM without hallucination. The structured snippets are perfect for feeding directly into your prompt.

1
from youdotcom import You
2
3
# Initialize
4
you = You()
5
6
# Search and extract context
7
def get_context(query):
8
    res = you.search(query=query, count=5)
9
    snippets = []
10
    if res.results and res.results.web:
11
        for result in res.results.web:
12
            if result.snippets:
13
                snippets.extend(result.snippets)
14
    return "\n".join(snippets)
15
16
user_question = "What is the current state of quantum computing?"
17
context = get_context(user_question)
18
19
# Feed to your LLM
20
prompt = f"Based on this information:\n{context}\n\nAnswer: {user_question}"

AI agent knowledge retrieval

Give your AI agents access to real-time web information. Perfect for building agents that need up-to-date facts, news, or specialized domain knowledge.

News monitoring & alerts

Track breaking news, competitor mentions, or industry trends. The automatic news classification ensures you get timely articles when relevant.

Content research & analysis

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

Knowledge base construction

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

Examples of Advanced Search Capabilities

Domain filtering

Restrict results to, exclude results from, or boost specific domains. Use include_domains for a strict allowlist, exclude_domains to filter out unwanted domains, and boost_domains to prefer matching domains without filtering out other results. For large domain lists, POST is strongly recommended.

1
from youdotcom import You
2
3
with You() as you:
4
  # Only return results from trusted news sources
5
  res = you.search(
6
    query="federal reserve interest rate decision",
7
    include_domains=["reuters.com", "apnews.com", "ft.com", "bloomberg.com"],
8
  )
9
10
  if res.results and res.results.web:
11
      for result in res.results.web:
12
          print(f"{result.title} — {result.url}")

Use boost_domains when you want to prefer sources without making them mandatory. Matching results from boosted domains receive a relative ranking boost, but the boost is not quantified. If boosted domains do not have matching results, results from other domains can still appear. boost_domains can be used with exclude_domains, but not with include_domains.

Search operators

Combine operators for powerful, precise searches:

1
from youdotcom import You
2
from youdotcom.models import Freshness
3
4
with You() as you:
5
  # Find PDFs about climate change from .edu sites published this year
6
  res = you.search(
7
      query="climate change site:.edu filetype:pdf",
8
      freshness=Freshness.YEAR,
9
  )
10
11
  # Print PDF results with their URLs
12
  if res.results and res.results.web:
13
      for result in res.results.web:
14
          print(f"{result.title}")
15
          print(f"  PDF URL: {result.url}")

Pagination

Use offset to retrieve additional pages of results. The offset value (0-9) skips that many pages, so offset=1 with count=10 returns results 11-20.

1
from youdotcom import You
2
3
with You() as you:
4
  # Get the second page of results
5
  res = you.search(
6
    query="machine learning",
7
    count=10,
8
    offset=1,
9
  )
10
11
  print(res.results.web)

Geographic targeting

Narrow down on results by country:

1
from youdotcom import You
2
from youdotcom.models import Country
3
4
# Get Swiss results
5
with You() as you:
6
  res = you.search(
7
    query="best restaurants in geneva",
8
    country=Country.CH,
9
  )
10
11
  # Print restaurant results with descriptions
12
  if res.results and res.results.web:
13
      for result in res.results.web:
14
          print(f"{result.title}")
15
          if result.description:
16
              print(f"  {result.description}\n")

Refer to the ISO 3166-1 alpha-2 standard for a list of country codes.

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:

1
if res.results and res.results.web:
2
    for result in res.results.web:
3
        process(result)
4
else:
5
    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 specify request parameters in the request to reduce noise and get more relevant results.

Request Format

Send parameters as a JSON body on POST /v1/search. Array fields are plain JSON arrays, with no ambiguity between comma-separated values and repeated params.

Pricing

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

All new accounts receive $100 in free credits to get started. 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
• 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

Full page content via extraction_mode: "full_page" (HTML, Markdown, or both) is billed separately from the base Web Search API rate.

Example: A single call with count=10 and extraction_mode: "full_page" returns 10 web results and 10 news results—20 pages total.

For volume discounts, annual pricing, or enterprise features, visit you.com/pricing or contact [email protected].

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.

Next Steps

Run in Postman

Use our Postman collections to learn and experiment on your own

API reference

Explore the complete API documentation with all parameters and response schemas

Search operators

Master advanced search operators to refine your queries

Quickstart guide

Get your API key and make your first search in 5 minutes