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

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):

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"}}'

Sources: You.com Docs, "Request Controls", the "POST /v1/search" API reference for the 1 to 100 count range and the 422 errors, and "Web Search API 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):

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

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):

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

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). The error reference adds the cases a client should not retry:

Source: You.com Docs, "Errors". 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). 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:

{"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.

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). Two protocols are supported:

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 is not available on keyless requests, because there is no account to attach it to (You.com Docs, "x402"). For background on the protocol, see our post on Cloudflare, x402, and Web Bot Auth.

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, Zero Data Retention on the Web Search and Answer APIs, and purchase through AWS Marketplace and Microsoft Azure Marketplace (You.com Docs).
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 and our guide to giving AI agents live web access. And if you need the page itself from a specific location, Massive's Web Render API returns clean HTML or markdown from any public source, in any location.

Sources

• You.com Docs, "Choose the Right API", "Web Search API Overview", "Web Search API Quickstart", "Request Controls", "Contents API Overview", "Rate Limits", "Errors", "MCP Server", "Machine Payments", "x402", "Zero Data Retention", "OpenAI GPT OSS", "Cloud Marketplaces"
• Built In, "AI Infrastructure Company You.com Raises $100M Series C", 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)