What Is the You.com Web Search API? Endpoint, Pricing, and Limits

TLDR: The You.com Web Search API is a single endpoint, POST https://ydc-index.io/v1/search, that returns ranked web and news results as JSON for your own model, RAG pipeline, or UI. As of September 2026 it costs $5.00 per 1,000 calls, self-serve accounts default to 10 requests per second, and new accounts get $100 in credits. Below: the request contract, response fields, cost math, limits, and when another You.com API fits better.

This page is the product reference for one specific API. If you are still deciding what a web search API is or how to compare providers, start with what a web search API is and how to choose one. For language walkthroughs, use the cURL guide, the Python SDK guide, or the TypeScript guide.

What Is the You.com Web Search API?

It is a retrieval endpoint with no synthesis step. You send a query, get ranked results with URLs, titles, descriptions, and text excerpts, and your code decides what to do with them. One request can return three sections. results.web holds the ranked web results. results.news appears when You.com's classifier detects news intent, such as a breaking event, so there is no separate news endpoint. results.knowledge carries licensed-data answers, such as stock prices or weather, when you set "knowledge": "core".

The docs state that the index is operated by You.com rather than resold from a third party. These are the facts an evaluator usually needs first:

Item	Value as of September 2026
Endpoint	`POST https://ydc-index.io/v1/search`. `GET` still works but receives no new features
Authentication	`X-API-Key` header. Keys are scoped per product
Result sections	Web, plus news when relevant and knowledge on request
Results per request	`count` from 1 to 100 per section, default 10
Price	$5.00 per 1,000 calls. Full-page extraction adds $1.00 per 1,000 pages crawled live
Default rate limit	10 requests per second on self-serve accounts
Free options	$100 in credits for new accounts, plus a keyless MCP profile with 100 queries per day
Clients	REST, the `youdotcom` Python SDK, the `@youdotcom-oss/sdk` TypeScript SDK, and a hosted MCP server

How Do You Send a First Request?

Create a key on the You.com platform and export it as YDC_API_KEY, the variable name the docs, SDKs, and integration examples all use. Then send one POST with two headers and a JSON body. This call asks for up to five results per section from the last month, with highlights instead of snippets:

curl -s -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "EU AI Act enforcement timeline",
    "count": 5,
    "freshness": "month",
    "extraction": {"extraction_mode": "highlights"}
  }' | jq '.results.web[]? | {title, url, page_age}'

Stay on POST for new work. The Web Search overview says GET /v1/search keeps running for existing integrations but gets no new features, and extraction and knowledge exist only on POST.

For application code, the REST contract is small enough to call with the Python standard library. The client below retries only on 429, honors Retry-After when the server sends a number of seconds, and flattens both sections into citation-ready rows. It reads highlights when present, falls back to snippets, and then to the description, because the reference defines no snippets or highlights field on news results.

import json
import os
import time
import urllib.error
import urllib.request

ENDPOINT = "https://ydc-index.io/v1/search"


def search(body, attempts=4, timeout=30):
    """POST one request body to the Web Search API, retrying only on HTTP 429."""
    data = json.dumps(body).encode("utf-8")
    headers = {
        "X-API-Key": os.environ["YDC_API_KEY"],
        "Content-Type": "application/json",
    }
    for attempt in range(attempts):
        request = urllib.request.Request(ENDPOINT, data=data, headers=headers, method="POST")
        try:
            with urllib.request.urlopen(request, timeout=timeout) as response:
                return json.load(response)
        except urllib.error.HTTPError as err:
            if err.code != 429 or attempt == attempts - 1:
                raise  # 401, 402, 403, and 422 need a fix, not a retry
            retry_after = (err.headers.get("Retry-After") or "").strip()
            time.sleep(int(retry_after) if retry_after.isdigit() else min(2 ** attempt, 60))


def evidence(payload):
    """Flatten web and news results into rows a prompt builder can cite."""
    rows = []
    results = payload.get("results") or {}
    for section in ("web", "news"):
        for hit in results.get(section) or []:
            contents = hit.get("contents") or {}
            passages = (
                contents.get("highlights")
                or hit.get("snippets")
                or [hit.get("description") or ""]
            )
            rows.append({
                "section": section,
                "url": hit.get("url"),
                "title": hit.get("title"),
                "page_age": hit.get("page_age"),
                "passages": passages,
            })
    return rows


if __name__ == "__main__":
    payload = search({
        "query": "EU AI Act enforcement timeline",
        "count": 5,
        "freshness": "month",
        "extraction": {"extraction_mode": "highlights"},
    })
    for row in evidence(payload):
        print(row["section"], row["url"], row["page_age"], len(row["passages"]))
    meta = payload.get("metadata") or {}
    print("search_uuid:", meta.get("search_uuid"), "latency_s:", meta.get("latency"))

If you prefer typed models, the official youdotcom SDK on PyPI is at version 3.5.0 and requires Python 3.10 or later. Pin the version you test against, since the knowledge docs say their Python example needs 3.5.0 or later. The Python SDK guide covers timeouts and retries in depth.

Which Request Parameters Change the Results?

Only query is required. Everything else narrows, pages, or enriches the result set. This table follows the API reference for POST /v1/search:

Parameter	Accepts	Default	Watch for
`query`	Text, including the `site:`, `filetype:`, `AND`, `OR`, `NOT`, `+`, and `-` operators	Required	Operators live in the query string
`count`	1 to 100	10	Per section, so 10 can mean 10 web plus 10 news
`offset`	0 to 9	0	Counts pages of size `count`
`freshness`	`day`, `week`, `month`, `year`, or `YYYY-MM-DDtoYYYY-MM-DD`	None	A broader time phrase in the query overrides it
`country`	ISO 3166-1 alpha-2 codes from a fixed list	None	36 countries in the current spec
`language`	BCP 47 codes from a fixed list of 51	`EN`	Sets the language of returned results
`safesearch`	`off`, `moderate`, `strict`	`moderate`	Explicit-content filtering
`include_domains`	Up to 500 domains	None	Strict allowlist, used without the other two lists
`exclude_domains`	Up to 500 domains	None	Can be combined with `boost_domains`
`boost_domains`	Up to 500 domains	None	A ranking preference, not a filter
`knowledge`	`core`	None	POST only, at no extra cost
`extraction`	Object with `extraction_mode` set to `highlights` or `full_page`	None	POST only. Full page can add cost
`crawl_timeout`	1 to 60 seconds	10	Full page only. The server rejects it alongside highlights

Two combinations fail with a 422: include_domains with exclude_domains, and include_domains with boost_domains. Pick an allowlist or a preference, not both. Freshness has a subtle rule: when the query contains a time phrase and you also set freshness, the broader window wins, so "news this week" with "freshness": "day" returns a week of results. Keep time words out of the query when a window must be strict.

Pagination counts pages. The request controls guide gives the example that offset 1 with count 10 returns results 11 to 20. Deduplicate by URL when you walk several pages, since a live index can shift between calls. The older livecrawl parameters still work but are deprecated in favor of extraction, so migrate them the next time you touch that code.

What Does the Response Contain?

Every response has a results object and a metadata object. Which fields appear depends on the section and the extraction mode, and most parsing bugs come from assuming a field is always present.

Field	Appears on	What to know
`url`, `title`, `description`	Web and news	The core record for display and citation
`snippets`	Web	Short, keyword-centered fragments. Omitted when you request highlights
`contents.highlights`	Web, in highlights mode	Passages ranked by relevance to your query
`contents.markdown`, `contents.html`	Web and news, in full-page mode	The whole page, present only on results crawled or cached successfully
`page_age`	Web and news	For news, the article's publication time in UTC. For web, only "the age of the search result"
`thumbnail_url`, `favicon_url`	Web, with thumbnails on news too	Interface assets, not evidence
`knowledge`	Requests with `"knowledge": "core"`	Up to 25 items with a title, description, provider attribution, and optional `as_of` date
`search_uuid`, `query`, `latency`	Metadata	Log the UUID for support tickets and the reported latency for your own percentiles

Treat results.news and results.knowledge as optional on every call: the first depends on the classifier, and the second is omitted rather than returned empty when nothing is relevant. Do not render knowledge attribution as a source link, because the reference describes those entries as provider credits with no URL. And do not read page_age on a web result as a crawl date or a verified publish date; check the page itself when a date carries weight. The page content guide documents the extraction options in full.

What Does the You.com Web Search API Cost?

Pricing is per call, not per result. As of September 2026, the billing docs and the pricing page list $5.00 per 1,000 calls with up to 100 results per call, and that rate includes news, highlights, and knowledge results. The one add-on is full-page extraction at $1.00 per 1,000 pages, counting only pages crawled live. extraction_source decides how many that is: blend, the default, serves cached pages free and crawls the rest, cache never crawls, and fetch crawls every result.

Full-page mode crawls every web and news result in the response, with no per-section switch, so the ceiling scales with count. Here is the math for 100,000 calls a month:

Configuration	Per call	100,000 calls
Snippets or highlights, any `count`	$0.005	$500
Full page with the `cache` source	$0.005	$500
Full page, `count` 5, every page crawled live	Up to $0.015	Up to $1,500
Full page, `count` 10, every page crawled live	Up to $0.025	Up to $2,500

The ceilings assume every query also fills a news section, which happens only when the classifier sees news intent, so real bills land between the rows. The docs warn against budgeting on a particular cache-hit rate, and the cache floor has a catch: results without a cached copy come back with no contents. The docs recommend highlights for RAG for this reason, since you get query-relevant passages with no page charge.

New accounts get $100 in credits with no credit card required, enough for 20,000 plain calls, and the MCP server's keyless free profile allows 100 queries per day. Agents without an account can pay per call in USDC through machine payments: $0.005 per call over x402 or $0.01 over MPP, with no Zero Data Retention on those keyless requests. Volume discounts and custom rate limits go through sales.

What Limits and Errors Should You Plan For?

Self-serve accounts default to 10 requests per second on /v1/search, and enterprise contracts set their own limits. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, a Unix timestamp, so an agent that fans out parallel searches can throttle itself before it hits a 429. The rate limits page says to honor Retry-After and shows exponential backoff capped at 60 seconds.

Status	Usual cause	What to do
400	Malformed request	Validate the JSON body before sending
401	Missing, invalid, or expired key	Check `YDC_API_KEY` in the environment that actually runs the code
402	Out of credits, or a payment challenge on keyless access	Add credits or enable Auto Top-Up. Keyless clients settle and retry
403	Key lacks Web Search scope, or the request went to the wrong host	Issue a key with the right scope. Answer, Research, and Finance Research run on `api.you.com`
422	Invalid parameter combination	Fix the `include_domains` pairing
429	Over the per-second limit	Honor `Retry-After`, then back off
500	Authentication or authorization middleware error	Retry sparingly and contact support if it persists

The 402 needs a production plan, not just a log line. Credits are prepaid, so a busy month can drain the balance mid-job. The billing docs describe Auto Top-Up, which organization admins can set to buy credits when the balance falls below a threshold, and call it the recommended way to prevent interruptions on production workloads. Every error body is in the error code reference.

When Should You Use a Different You.com API?

The Web Search API is one of five REST APIs that share the X-API-Key header, although each key needs the right product scope. The Choose the Right API page frames the decision around what your code needs back:

Your code needs	Use	Price as of September 2026
Ranked results to filter, rerank, render, or feed your own model	Web Search API	$5.00 per 1,000 calls
Page text from URLs you already have	Contents API	$1.00 per 1,000 pages
One cited answer from a single search pass	Answer API	$5.00 per 1,000 calls
Multi-step research with depth control	Research API	$12 (lite) to $1,200 (frontier) per 1,000 calls
Cited answers about filings, prices, and fundamentals	Finance Research API	$110 (deep) or $500 (exhaustive) per 1,000 calls

The comparison worth running is Web Search against Answer, because they cost the same per call. The Answer API returns a Markdown answer with verbatim citation excerpts plus the web results it used, at a documented p50 latency of 2.67 seconds. Choose it when a cited answer is the product and you would otherwise pay for model tokens to write one. Stay with Web Search when you need to pick the model, control the prompt and evidence, cache or rerank results, or show results in an interface. For the category view, see the explainers on AI answer APIs and research APIs.

Skip search when you already know the URLs; the Contents API explainer covers that path and when full-page extraction inside a search call fits better. For agents and IDEs, the hosted MCP server at https://api.you.com/mcp exposes you-search, you-contents, you-balance, and you-discover by default, with a Bearer key or OAuth 2.1. Research and finance tools sit behind /mcp/research and /mcp/finance. There is no you-answer tool, so one-pass answers go over REST.

What Should You Test Before You Commit?

A spec sheet does not tell you whether results fit your queries. Run these checks with your own traffic first:

Relevance on a frozen query set. Use real queries from your logs. The web search API evaluation guide lays out a paired method, and the docs publish You.com's own evaluation approach.
News frequency. Count how often results.news appears for your mix. It changes your parsing paths and doubles the maximum pages a full-page call can crawl.
Highlights versus snippets. Run the same prompts with each and compare answer quality and token counts.
Latency split. Log the metadata.latency value the API reports next to your own wall-clock time, and investigate when the two diverge.
Failure paths. Force a 401, a 403 from a wrongly scoped key, a 422 domain combination, and a burst past 10 requests per second, and confirm each lands in the right handler.
The bill at your settings. Price your real count and extraction mode at the ceiling, then compare actual usage against it.
Data handling. Zero Data Retention covers the Web Search and Answer APIs on enterprise agreements, enabled on request. It limits what You.com retains, but queries still leave your network, so it is not the same as keeping traffic on your own infrastructure.