# Customer Spotlight: You.com Search API, Pricing, and MCP Server for AI Agents The You.com Search API is a web search endpoint built for AI agents and RAG pipelines: you send a query and get ranked web and news results back as JSON, with query-relevant highlights or full page content attached. It costs $5.00 per 1,000 calls, according to [You.com's docs](https://you.com/docs/choose-the-right-api). Around it, You.com offers Contents, Answer, Research, and Finance Research APIs, an Inference Router for open-weight models, and a hosted MCP server that agents can use with no API key at all. You.com is a Massive customer, and this spotlight explains how its search API works. > **Key Takeaways** > > - The You.com Search API is one `POST` to `https://ydc-index.io/v1/search` with an `X-API-Key` header. It returns up to 100 results per call for **$5.00 per 1,000 calls**. > - Results come with **snippets, highlights, or full page** Markdown or HTML, chosen with `extraction_mode`. Full page adds $1.00 per 1,000 pages fetched live. > - Five more APIs share the same key: Contents ($1.00 per 1,000 pages), Answer, Research ($12 to $1,200 per 1,000 by effort tier), Finance Research, and the Inference Router. > - The **keyless MCP profile** gave us 10 of 10 successful searches, 10 results each, at a **0.742 s median server latency**. > - Agents can also pay **per request in USDC** through x402 ($0.005 per search) or MPP ($0.01), with no account. ## What is the You.com Search API? The You.com Web Search API delivers "high-quality, structured web and news results optimized for programmatic access in AI applications" ([You.com Docs](https://you.com/docs/guides/search)). It does retrieval only, with no answer-writing step, so your own model decides what to do with the results. That makes it a fit for agents, RAG pipelines, and search UIs that need fresh, citable sources. You.com started as a consumer AI search engine and now focuses on APIs for developers and enterprises. It serves "over 1 billion deeply researched, AI-generated answers a month through its APIs" ([Built In](https://builtin.com/articles/youcom-100m-series-c-1b-valuation-20250908)). Its search also powers other tools. You.com is the default backend for the browser tool in OpenAI's open-weight `gpt-oss-120b` and `gpt-oss-20b` models: "When a GPT OSS model needs to search the web, open a page, or find content, it calls You.com under the hood" ([You.com Docs](https://you.com/docs/integrations/gpt-oss)). ## How does a You.com Search API request work? Every call goes to `POST /v1/search` on `ydc-index.io`, with the key in the `X-API-Key` header. The body takes a `query` plus optional controls ([You.com Docs](https://you.com/docs/guides/search/quickstart)):
BASH
curl -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 deadlines",
       "count": 5,
       "country": "DE",
       "freshness": "week",
       "extraction": {
         "extraction_mode": "highlights"}}'
| Parameter | What it does | |---|---| | `query` | The search phrase. Inline operators such as `site:` are supported | | `count` | Results to return, up to 100 per call (up to 50 with highlights) | | `country`, `language` | ISO 3166-1 country code and BCP 47 language code | | `freshness` | `day`, `week`, `month`, `year`, or a `YYYY-MM-DDtoYYYY-MM-DD` range | | `offset` | Page number, 0 to 9. `offset=1` with `count=10` returns results 11 to 20 | | `include_domains`, `exclude_domains`, `boost_domains` | Allowlist (up to 500), blocklist (up to 5,000), or a soft ranking boost (up to 500) | | `extraction` | `highlights` for query-relevant passages, `full_page` for Markdown or HTML of each result | Sources: [You.com Docs, "Request Controls"](https://you.com/docs/guides/search/request-controls), the ["POST /v1/search" API reference](https://you.com/docs/api-reference/search/v1-search) for the 1 to 100 count range and the 422 errors, and ["Web Search API Quickstart"](https://you.com/docs/guides/search/quickstart), for the 50-result cap with highlights. Two details are worth knowing before you build on it. Raw HTTP calls return short `snippets` unless you set `extraction`, while the Python SDK 3.6.0 and later sends highlights by default. And `include_domains` cannot be combined with `exclude_domains` or `boost_domains` in one request; that returns `422`. ## Snippets, highlights, or full page: picking an extraction mode The `extraction` setting decides how much of each page comes back, and it is the main cost and context-size lever ([You.com Docs](https://you.com/docs/guides/search)): | Mode | Returns | Best for | Extra cost | |---|---|---|---| | Snippets (default over HTTP) | Short excerpts per result | Rendering a results UI | None | | `highlights` | Query-relevant passages from each page | Grounding an agent or RAG prompt | None | | `full_page` | Clean Markdown or HTML of each result | Indexing or full-document analysis | $1.00 per 1,000 pages fetched live | If you already have the URLs and don't need to search, the separate Contents API returns Markdown or HTML for a list of pages at $1.00 per 1,000 ([You.com Docs](https://you.com/docs/guides/contents)). Markdown matters for agents because it strips layout markup the model would otherwise pay tokens to read, a point we covered in [how HTML-to-Markdown cuts agent token costs](https://www.joinmassive.com/blog/skip-the-browser-how-html-to-markdown-cuts-agent-token-costs-by-80). ## How much does the You.com API cost? You.com's API pricing is pay-as-you-go, per call, with each API priced separately ([You.com Docs](https://you.com/docs/choose-the-right-api)): | API | Endpoint | Price | Latency (You.com's figures) | |---|---|---|---| | Web Search | `ydc-index.io/v1/search` | $5.00 per 1,000 calls | Retrieval only | | Contents | `ydc-index.io/v1/contents` | $1.00 per 1,000 pages | Up to 10 s per URL by default | | Answer | `api.you.com/v1/answer` | $5.00 per 1,000 calls | p50 2.67 s | | Research | `api.you.com/v1/research` | $12 (`lite`) to $1,200 (`frontier`) per 1,000 | Under 10 s to background-only | | Finance Research | `api.you.com/v1/finance_research` | $110 (`deep`) or $500 (`exhaustive`) per 1,000 | Under 120 s or under 300 s | | Inference Router | `api.you.com/v1/chat/completions` | Varies by model | Varies by model | The Research API trades latency for depth through `research_effort`, in five tiers: `lite` ($12 per 1,000, under 10 s), `standard` ($50, about 10 to 30 s), `deep` ($100, under 120 s), `exhaustive` ($450, under 300 s), and `frontier` ($1,200, background only, p50 300 s). The docs advise picking "the lowest tier that answers the question." New accounts start with free credits ([You.com Docs](https://you.com/docs/welcome)). ![Six You.com APIs and the MCP server on two hosts: Web Search and Contents on ydc-index.io; Answer, Research, Finance Research and Inference Router on api.you.com.](assets/youcom-api-map.png "The six You.com APIs, plus the MCP server, and the host each one runs on, from You.com's documentation.") Note the two hosts. Keyed Web Search and Contents calls go to `ydc-index.io`; Answer, Research, Finance Research, and the Inference Router run only on `api.you.com`. When we sent a Research request to `ydc-index.io` with a placeholder key, it returned `403` with `{"message":"Missing Authentication Token"}`, exactly as the docs describe for a path on the wrong host. Check the host first if you see that message with a valid key. ## Rate limits and error handling Self-serve accounts get 10 requests per second on Search, Contents, Answer, and Research, and 5 on Finance Research. Enterprise plans set their own limits by contract. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`, and a `429` may include `Retry-After` ([You.com Docs](https://you.com/docs/rate-limits)). The error reference adds the cases a client should not retry: | HTTP | Meaning | Retry? | |---|---|---| | 400, 422 | Bad parameters or an invalid combination | No, fix the request | | 401 | Missing, invalid, or expired key | No, check the key | | 402 | Out of credits (keyed), or a payment challenge (keyless) | No, add credits or pay | | 403 | Key lacks scope, or path is on the wrong host | No, check scope and host | | 429 `spend_cap_exceeded` | The key hit its spending cap | No, raise the cap | | 429 (any other) | Rate limited | Yes, after `Retry-After` or with backoff | | 500 | Server error | Contact support if persistent | Source: [You.com Docs, "Errors"](https://you.com/docs/using-the-api/error-code-reference). The spend-cap case is easy to miss: it shares the 429 status with a normal rate limit, but the docs say "retrying does not help." ## What we saw with the keyless MCP server You.com runs a hosted MCP server at `https://api.you.com/mcp`, so tools like Claude Code, Cursor, and other MCP clients can call search and contents as tools, with research and finance on their own paths ([You.com Docs](https://you.com/docs/agents/mcp-server)). Adding `?profile=free` exposes two tools, `you-search` and `you-discover`, with no API key and a limit of 100 queries per day. The minimal client config is a single URL:
JSON
{"mcpServers": {
  "youdotcom": {
    "type": "http",
    "url": "https://api.you.com/mcp?profile=free"
  }}}
On November 4, 2026, we connected to the free profile, listed its tools, and ran 10 `you-search` queries with `count` set to 10, from news and finance to code and local food. The server identified itself as "You.com" version 4.0.7. | Measure | Result | |---|---| | Successful calls | 10 of 10 (HTTP 200) | | Web results per query | 10 of 10 requested, every query | | Results carrying highlights | 100 of 100 (the MCP default is `highlights`) | | Median server-reported latency | 0.742 s (range 0.409 to 0.965 s) | | Median round trip from our client | 1.267 s | The server-reported figure is the `latency` field You.com returns in each response's metadata. The round trip adds the network path from our test machine, so yours will differ. ## Can an AI agent pay for You.com search without an API key? Yes. The Web Search and Finance Research APIs accept machine payments, where "a client can call either one and settle payment for that call inside the same HTTP exchange, with no signup, no API key, and no prepaid credit balance" ([You.com Docs](https://you.com/docs/administration/machine-payments)). Two protocols are supported: | Protocol | Settles in | Web Search per call | Finance Research `deep` | |---|---|---|---| | x402 | USDC on Base or Solana | $0.005 | $0.11 | | MPP | USDC on Tempo | $0.01 | $0.11 | Machine payments use a different request than the keyed examples above: a `GET` to `api.you.com/v1/search` with query-string parameters, because `POST /v1/search` does not offer payment terms. We sent an unpaid `GET` there. It returned `402 Payment Required` with a `PAYMENT-REQUIRED` header for x402 and a `WWW-Authenticate: Payment` header for MPP, so one response offered terms for both. Decoded, the x402 terms asked for 5,000 base units of USDC, which is $0.005 since USDC uses six decimals, on Base or Solana, valid for 600 seconds. That matches the price table. A payment-capable client signs and retries; the docs recommend an official x402 SDK rather than signing by hand. Two limits apply: challenge issuance is capped at 10 per minute per caller, and [Zero Data Retention](https://you.com/docs/administration/zero-data-retention) is not available on keyless requests, because there is no account to attach it to ([You.com Docs, "x402"](https://you.com/docs/administration/machine-payments/x402)). For background on the protocol, see our post on [Cloudflare, x402, and Web Bot Auth](https://www.joinmassive.com/blog/cloudflare-x402-web-bot-auth-ai-agents). ## Who is the You.com Search API for? The You.com Search API fits four kinds of teams: 1. **Teams building agents and RAG pipelines.** Highlights put query-relevant passages straight into the prompt, and the higher-level APIs cover cited answers and multi-step research when you don't want to build that loop. 2. **Developers working inside coding agents.** The MCP server and plugins for Claude Code, Cursor, Codex, and other harnesses add web search to the tools a developer already uses, with a keyless free tier. 3. **Enterprises with procurement and data rules.** You.com lists [SSO and SCIM](https://you.com/docs/administration/sso-scim), [Zero Data Retention](https://you.com/docs/administration/zero-data-retention) on the Web Search and Answer APIs, and purchase through AWS Marketplace and Microsoft Azure Marketplace ([You.com Docs](https://you.com/docs/integrations/cloud-marketplaces)). 4. **Autonomous agents that need to pay their own way.** x402 and MPP let an agent buy a single search with no human setting up an account. You.com's docs also say the API can run beside another index: "There is no exclusive-index requirement." For a wider view of where search APIs fit, see our [LLM search stack map](https://www.joinmassive.com/blog/llm-search-stack-2026) and our guide to [giving AI agents live web access](https://www.joinmassive.com/blog/how-to-give-ai-agents-live-web-access). And if you need the page itself from a specific location, Massive's [Web Render API](https://www.joinmassive.com/blog/introducing-massive-web-render-api) returns clean HTML or markdown from any public source, in any location. ## Frequently Asked Questions ### What is the You.com Search API? It is You.com's Web Search API, a REST endpoint at `ydc-index.io/v1/search` that returns ranked web and news results as JSON for AI agents, RAG pipelines, and search interfaces. Results can include snippets, query-relevant highlights, or full page content. ### How much does the You.com API cost? The Web Search API costs $5.00 per 1,000 calls, with full page content at $1.00 per 1,000 pages fetched live. The Contents API is $1.00 per 1,000 pages, the Answer API $5.00 per 1,000 calls, and the Research API $12 to $1,200 per 1,000 depending on effort tier. New accounts start with free credits. ### Does You.com have an MCP server? Yes. The hosted server at `https://api.you.com/mcp` exposes search and contents tools to MCP clients, with research and finance on their own paths, `/mcp/research` and `/mcp/finance`. The `?profile=free` version needs no API key and allows 100 `you-search` queries per day. ### How do I authenticate with the You.com API? Send your key in the `X-API-Key` header; the docs use the `YDC_API_KEY` environment variable. The Inference Router and the MCP server use `Authorization: Bearer` instead, and the MCP server also supports OAuth. ## Sources - You.com Docs, ["Choose the Right API"](https://you.com/docs/choose-the-right-api), ["Web Search API Overview"](https://you.com/docs/guides/search), ["Web Search API Quickstart"](https://you.com/docs/guides/search/quickstart), ["Request Controls"](https://you.com/docs/guides/search/request-controls), ["Contents API Overview"](https://you.com/docs/guides/contents), ["Rate Limits"](https://you.com/docs/rate-limits), ["Errors"](https://you.com/docs/using-the-api/error-code-reference), ["MCP Server"](https://you.com/docs/agents/mcp-server), ["Machine Payments"](https://you.com/docs/administration/machine-payments), ["x402"](https://you.com/docs/administration/machine-payments/x402), ["Zero Data Retention"](https://you.com/docs/administration/zero-data-retention), ["OpenAI GPT OSS"](https://you.com/docs/integrations/gpt-oss), ["Cloud Marketplaces"](https://you.com/docs/integrations/cloud-marketplaces) - Built In, ["AI Infrastructure Company You.com Raises $100M Series C"](https://builtin.com/articles/youcom-100m-series-c-1b-valuation-20250908), September 2025 - Massive, keyless test of the You.com MCP free profile (10 `you-search` queries), wrong-host check, and x402 discovery request, November 4, 2026 (first-party test)