> For clean Markdown of any page, append `.md` to the page URL. > Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL). > Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key). > Call live You.com APIs: Product MCP at https://api.you.com/mcp (keyless `?profile=free` exposes `you-search` and `you-discover`. Research and finance use `/mcp/research`, `/mcp/finance`, or `?tools=` on `/mcp`). To pick an API or integration path, call `you-discover` on that server instead of guessing. > OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`. # Web Search API > Web Search, Answer, Contents, Research, and Finance Research APIs that give your AI app real-time web intelligence. Start with free credits. ## Docs - [Web Search API Quickstart](https://you.com/docs/guides/search/quickstart.md): Get an API key and run your first Web Search API request. Returns real-time web and news results as LLM-ready JSON. - [Knowledge](https://you.com/docs/guides/search/knowledge.md): Set knowledge to core on POST /v1/search to get stock and crypto prices, weather, sports, and economic data from licensed providers in the same call as web results. - [Retrieve page content](https://you.com/docs/guides/search/retrieve-page-content.md): Extract full HTML or Markdown page content from search results. Ideal for RAG, knowledge base construction, and deep content analysis. - [Get live news](https://you.com/docs/guides/search/live-news.md): Retrieve real-time news results from the You.com Web Search API. Filter by recency, country, language, and more. - [Request Controls](https://you.com/docs/guides/search/request-controls.md): Control Web Search API results with freshness, country, language, domain filters, pagination, and safesearch. - [Search operators](https://you.com/docs/guides/search/search-operators.md): Discover the search operators and learn how to use them - [How to Evaluate You.com Web Search API](https://you.com/docs/guides/search/evaluate-us.md): A practical guide to benchmarking You.com's Web Search API: methodology, configurations, datasets, and real performance tradeoffs. - [The Best Web Search API for AI Agents](https://you.com/docs/guides/search/web-search-api-for-ai-agents.md): The You.com Web Search API is built for AI agents, assistants, coding copilots, and RAG pipelines. Structured snippets, real-time web, one endpoint. - [The Best API for Grounding LLM Responses with Citations](https://you.com/docs/guides/search/grounding-llm-responses-with-citations.md): Add citations and real-time source grounding to any LLM with the You.com Web Search API. Step-by-step guide with code, schema, and production patterns. > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append `.md` to the page URL. > Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL). > Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key). > Call live You.com APIs: Product MCP at https://api.you.com/mcp (keyless `?profile=free` exposes `you-search` and `you-discover`. Research and finance use `/mcp/research`, `/mcp/finance`, or `?tools=` on `/mcp`). To pick an API or integration path, call `you-discover` on that server instead of guessing. > OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`. # Web Search API Overview > **Tip** > > **Add You.com to your agent or IDE via MCP**—connect at `https://api.you.com/mcp`. Try search with no signup at `https://api.you.com/mcp?profile=free` (`you-search` and `you-discover`). Research and finance use `/mcp/research` and `/mcp/finance`, or `?tools=` on `/mcp`. [MCP Server guide →](/docs/agents/mcp-server) > **Install the Docs MCP server** > > The Docs MCP server lets your agent search over the entirety of these docs. Free to use. > > Install `https://you.com/docs/_mcp/server`. See the [Docs MCP Server guide](/docs/agents/docs-mcp-server) to learn more. --- ## What Is the You.com Web Search API? The You.com Web Search API delivers high-quality, [structured web and news results](https://you.com/resources/what-is-a-search-api-for-llms) 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](/docs/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. | API | Endpoint | Guide | API reference | | -------------------- | -------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------- | | Web Search API | `POST https://ydc-index.io/v1/search` (also `GET`) | [Overview](/docs/guides/search) | [/v1/search](/docs/api-reference/search/v1-search) | | Contents API | `POST https://ydc-index.io/v1/contents` | [Overview](/docs/guides/contents) | [/v1/contents](/docs/api-reference/contents) | | Answer API | `POST https://api.you.com/v1/answer` | [Overview](/docs/guides/answer) | [/v1/answer](/docs/api-reference/answer/v1-answer) | | Research API | `POST https://api.you.com/v1/research` | [Overview](/docs/guides/research) | [/v1/research](/docs/api-reference/research/v1-research) | | Finance Research API | `POST https://api.you.com/v1/finance_research` | [Overview](/docs/guides/finance-research) | [/v1/finance_research](/docs/api-reference/finance-research/v1-finance_research) | 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: | Request | Text returned per result | | ------------------------------- | ---------------------------------------------------------------------------------- | | No `extraction` | `snippets`—short, keyword-centered fragments | | `extraction_mode: "full_page"` | `snippets`, plus `contents.markdown` or `contents.html` carrying the whole page | | `extraction_mode: "highlights"` | `contents.highlights`—the passages that address your query. `snippets` are omitted | Our classification system determines when to include news results based on query intent. Set `knowledge: "core"` to also request [licensed-data results](/docs/guides/search/knowledge) 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 ```json maxLines=20 { "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. | | Snippets | Highlights | Full page | | -------------- | ------------------------ | -------------------------------- | ------------------------------------- | | Returned by | Default, no `extraction` | `extraction_mode: "highlights"` | `extraction_mode: "full_page"` | | Response field | `snippets` | `contents.highlights` | `contents.markdown` / `contents.html` | | Selected by | Keyword match | Relevance to your query | Whole page | | Best for | Rendering a results UI | Grounding an agent or RAG prompt | Archiving, full-document analysis | See [Retrieve page content](/docs/guides/search/retrieve-page-content) for highlights vs. full page, `extraction_source`, crawl timeout, and the Contents API comparison. | Feature | What it does | | ------------------------------------------------------------------ | ------------------------------------------------------------------- | | [Knowledge](/docs/guides/search/knowledge) | Licensed-data results in `results.knowledge` | | [Retrieve page content](/docs/guides/search/retrieve-page-content) | Highlights or full page Markdown/HTML per result | | [News Results](/docs/guides/search/live-news) | News articles when the query has news intent | | [Request Controls](/docs/guides/search/request-controls) | Freshness, country, language, domains, pagination, safesearch | | [Search operators](/docs/guides/search/search-operators) | `site:`, `filetype:`, `AND`, `OR`, `NOT`, `+`, and `-` in the query | If you already have URLs and do not need to search first, use the [Contents API](/docs/guides/contents). --- ## Parameters | Parameter | Type | Description | | ----------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Your search query (supports [search operators](/docs/guides/search/search-operators)) | | `count` | integer | Max results per section (default varies, max 100) | | `freshness` | string | `day`, `week`, `month`, `year`, or date range | | `country` | string | Country code (e.g., `US`, `GB`, `FR`) | | `language` | string | BCP 47 language code (e.g., `EN`, `JA`, `DE`) | | `offset` | integer | For pagination (0-9) | | `safesearch` | string | `off`, `moderate` (default), `strict` | | `knowledge` | string | `core`. Requests [knowledge results](/docs/guides/search/knowledge). POST only | | `extraction` | object | Content to extract per result. `extraction_mode` is `full_page` or `highlights`. POST only | | `extraction.extraction_source` | string | Where `full_page` content comes from: `blend` (default), `cache`, or `fetch` | | `extraction.full_page.extraction_formats` | array | `html`, `markdown`, or both. Defaults to `["markdown"]` | | `crawl_timeout` | integer | Maximum crawl timeout in seconds (`1-60`, default `10`). Applies only when `extraction_mode` is `full_page` | | `include_domains` | string (GET) / array (POST) | Restrict results to these domains. GET: comma-separated string. POST: JSON array. Supports up to 500 domains | | `exclude_domains` | string (GET) / array (POST) | Exclude results from these domains. GET: comma-separated string. POST: JSON array. Supports up to 5000 domains | | `boost_domains` | string (GET) / array (POST) | Boost results from these domains without excluding other domains. GET: comma-separated string. POST: JSON array. Supports up to 500 domains. Cannot be used with `include_domains` | [View full API reference](/docs/api-reference/search/v1-search) Send parameters as a JSON body on `POST /v1/search`. Array fields are plain JSON arrays. > **Note** > > `GET /v1/search` still works and existing integrations will keep running, but it will not receive new feature updates. New features will be added to `POST` only, and `extraction` and `knowledge` are only available there. On GET, domain filters must also fit in a single comma-separated query string value and are subject to URL length limits. --- ## Common Use Cases ### RAG (Retrieval-Augmented Generation) Use search snippets to provide context to your LLM without [hallucination](https://you.com/resources/ai-hallucination-prevention-guide). The structured snippets are ready to feed into a prompt. For token-sensitive pipelines, request [highlights](/docs/guides/search/retrieve-page-content) instead. #### [Deep Search template](/docs/examples/deep-search) See a working app that uses multi-pass query expansion to surface more relevant results. ```python 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. #### [Simple Search template](/docs/examples/simple-search) See a working app that runs a web search and returns the top results. ### News monitoring & alerts Track breaking news, competitor mentions, or industry trends. Classification includes news results when they are relevant. See [News Results](/docs/guides/search/live-news). ### Content research & analysis Gather information from multiple sources for content creation, competitive intelligence, or market research. ### Knowledge base construction Use [full page extraction](/docs/guides/search/retrieve-page-content) 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: ```python 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](/docs/guides/search/search-operators) and [request controls](/docs/guides/search/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](/docs/administration/billing#web-search-api) 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](/docs/administration/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](/docs/guides/search/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. | Line item | Calculation | Cost | | ---------------------------------- | ------------------------- | ----------- | | Web Search API call | 1 call × \$5.00 / 1,000 | \$0.005 | | Full page extraction, crawled live | 18 pages × \$1.00 / 1,000 | \$0.018 | | Full page extraction, from cache | 2 pages × \$0.00 | \$0.000 | | **Total** | | **\$0.023** | 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](/docs/administration/billing) for the full breakdown. For volume discounts, annual pricing, or enterprise features, visit [you.com/pricing](https://you.com/pricing) or contact [api@you.com](mailto: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](/docs/administration/zero-data-retention) for what it covers and how to enable it. --- ## FAQ #### Can I use You.com alongside another web index? Yes. Call the Web Search API next to the index you already use and combine or route results in your application. There is no exclusive-index requirement. #### Can I use the APIs without an LLM? Yes. The Web Search API and the Contents API return structured JSON—URLs, titles, snippets, and optional page text—so you can drive a search UI or a retrieval pipeline that never calls a model. --- ## Next Steps #### [Quickstart](/docs/guides/search/quickstart) Make your first Web Search API request #### [API reference](/docs/api-reference/search/v1-search) Explore the complete API documentation with all parameters and response schemas #### [Retrieve page content](/docs/guides/search/retrieve-page-content) Highlights vs. full page content per result #### [How to Evaluate](/docs/guides/search/evaluate-us) Benchmark retrieval quality, latency, and freshness