*** title: Quickstart og:title: You.com API Quickstart | Search, Contents & Research APIs for AI Applications og:description: Get from zero to working API requests in minutes. Covers the Search API, Contents API, Research API, live crawling, evaluation, and pricing — everything you need to evaluate You.com. --------------------- For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://you.com/docs/llms.txt. For full documentation content, see https://you.com/docs/llms-full.txt. You.com gives you real-time web intelligence through three core APIs: Search, Contents, and Research. This quickstart will get you searching the web and answering questions within minutes. Then, we'll show you how to [evaluate us](/docs/evaluate-us). *** ## What You.com offers Returns real-time web and news results as structured, LLM-ready JSON. Use it to ground your AI in fresh information — feed search results directly into your prompt to answer questions without hallucination. Add the `livecrawl` parameter and each result comes back with its full page content, not just a snippet. Give it a list of URLs, get back clean Markdown or HTML. No browser automation, no HTML parsing. One idea: pass your competitors' pricing page URLs to a daily job, get clean Markdown back, and feed that to an LLM to monitor what changed. Ask a complex question, get a thorough, well-cited answer. Research runs multiple searches, reads through the sources, and synthesizes everything — so you don't have to. Control the depth with `research_effort` from `lite` to `exhaustive`. *** ## Get your API key Sign in or create an account, then get an API key here: [https://you.com/platform](https://you.com/platform). You'll start with \$100 in complimentary credits — no credit card required. ## Try the Search API The Search API takes a natural language query and returns structured web and news results. ```python from youdotcom import You with You(api_key_auth="api_key") as you: results = you.search.unified(query="global birth rate trends", count=5) for result in results.results.web: print(result.title) print(result.url) if result.snippets: print(result.snippets[0]) ``` ```typescript import { You } from "@youdotcom-oss/sdk"; const you = new You({ apiKeyAuth: "api_key" }); const result = await you.search({ query: "global birth rate trends", count: 5 }); result.results?.web?.forEach((r) => { console.log(r.title, r.url); console.log(r.snippets?.[0]); }); ``` ```curl curl -G https://ydc-index.io/v1/search \ -H "X-API-Key: api_key" \ --data-urlencode "query=global birth rate trends" \ -d count=5 ``` You'll get back structured JSON like this: ```json maxLines=20 { "results": { "web": [ { "url": "https://www.worldbank.org/en/topic/population", "title": "Population | World Bank", "description": "The World Bank tracks global birth rate and population trends.", "snippets": [ "Global fertility rates have declined significantly over the past five decades, falling from an average of 5 births per woman in 1960 to around 2.3 today." ], "page_age": "2025-10-01T00:00:00", "authors": [], "favicon_url": "https://ydc-index.io/favicon?domain=worldbank.org&size=128" } ] }, "metadata": { "query": "global birth rate trends", "search_uuid": "a1b2c3d4-0000-0000-0000-000000000000", "latency": 0.38 } } ``` Learn how to use [our SDKs](/docs/sdks/python-sdk) to run the example code above. ### Improve accuracy with livecrawl Search results already include snippets — short, query-relevant text extracts from target pages. Use the `livecrawl` parameter to fetch full page content for each result as clean Markdown or HTML. This will naturally increase latency, but massively improves knowledge accuracy. ```python from youdotcom import You from youdotcom.models import LiveCrawl, LiveCrawlFormats with You(api_key_auth="api_key") as you: results = you.search.unified( query="global birth rate trends", count=5, livecrawl=LiveCrawl.ALL, livecrawl_formats=LiveCrawlFormats.MARKDOWN, ) for result in results.results.web: if result.contents: print(result.title) print(result.contents.markdown[:400]) ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import { LiveCrawl, LiveCrawlFormats } from "@youdotcom-oss/sdk/models"; const you = new You({ apiKeyAuth: "api_key" }); const result = await you.search({ query: "global birth rate trends", count: 5, livecrawl: LiveCrawl.All, livecrawlFormats: LiveCrawlFormats.Markdown, }); result.results?.web?.forEach((r) => { if (r.contents?.markdown) { console.log(r.title); console.log(r.contents.markdown.slice(0, 400)); } }); ``` ```curl curl -G https://ydc-index.io/v1/search \ -H "X-API-Key: api_key" \ --data-urlencode "query=global birth rate trends" \ -d count=5 \ -d livecrawl=all \ -d livecrawl_formats=markdown ``` Results that support live crawling will include a `contents.markdown` field with the full page. For RAG pipelines that need deep context rather than surface-level snippets, this is the parameter to reach for. [Full Search API reference and all parameters](/docs/search/overview) ## Try the Contents API The Contents API fetches content from URLs you specify, either as raw HTML, Markdown or both. ```python from youdotcom import You from youdotcom.models import ContentsFormats with You(api_key_auth="api_key") as you: pages = you.contents.generate( urls=[ "https://competitor-a.com/pricing", "https://competitor-b.com/pricing", ], formats=[ContentsFormats.MARKDOWN], ) for page in pages: print(f"=== {page.title} ===") print(page.markdown) ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import { ContentsFormats } from "@youdotcom-oss/sdk/models"; const you = new You({ apiKeyAuth: "api_key" }); const pages = await you.contents({ urls: [ "https://competitor-a.com/pricing", "https://competitor-b.com/pricing", ], formats: [ContentsFormats.Markdown], }); for (const page of pages) { console.log(`=== ${page.title} ===`); console.log(page.markdown?.slice(0, 500)); } ``` ```curl curl -X POST https://ydc-index.io/v1/contents \ -H "X-API-Key: api_key" \ -H "Content-Type: application/json" \ -d '{ "urls": ["https://competitor-a.com/pricing", "https://competitor-b.com/pricing"], "formats": ["markdown"] }' ``` Each URL comes back as a structured object: ```json [ { "url": "https://competitor-a.com/pricing", "title": "Pricing — Competitor A", "markdown": "# Pricing\n\n## Starter\n$49/month...", "metadata": { "site_name": "Competitor A", "favicon_url": "https://ydc-index.io/favicon?domain=competitor-a.com&size=128" } } ] ``` [Full Contents API reference and all parameters](/docs/contents/overview) ## Try the Research API The Research API goes beyond a single web search. Give it a complex question and it runs multiple searches, reads through the sources, and synthesizes a thorough, citation-backed answer. ```python from youdotcom import You from youdotcom.models import ResearchEffort you = You(api_key_auth="api_key") res = you.research( input="What are the tradeoffs between microservices and monolithic architectures for high-traffic applications?", research_effort=ResearchEffort.STANDARD, ) print(res.output.content[:500]) print(f"\nSources: {len(res.output.sources)}") for source in res.output.sources: print(f" - {source.title or 'Untitled'}: {source.url}") ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import type { ResearchRequest } from "@youdotcom-oss/sdk/models/operations"; import { ResearchEffort } from "@youdotcom-oss/sdk/models/operations"; const you = new You({ apiKeyAuth: "api_key" }); const request: ResearchRequest = { input: "What are the tradeoffs between microservices and monolithic architectures for high-traffic applications?", researchEffort: ResearchEffort.Standard, }; const result = await you.research(request); console.log(result.output.content.slice(0, 500)); console.log(`\nSources: ${result.output.sources.length}`); result.output.sources.forEach((s) => { console.log(` - ${s.title ?? s.url}: ${s.url}`); }); ``` ```curl curl -X POST https://api.you.com/v1/research \ -H "X-API-Key: api_key" \ -H "Content-Type: application/json" \ -d '{ "input": "What are the tradeoffs between microservices and monolithic architectures for high-traffic applications?", "research_effort": "standard" }' ``` The response includes a Markdown-formatted answer with inline citations and the list of sources used: ```json maxLines=20 { "output": { "content": "## Microservices vs Monolithic Architectures\n\nThe choice between microservices and monolithic architectures involves several key tradeoffs...\n\n### Scalability\nMicroservices allow independent scaling of individual components [[1, 3]]...", "content_type": "text", "sources": [ { "url": "https://example.com/architecture-patterns", "title": "Architecture Patterns for High-Traffic Systems", "snippets": [ "Microservices enable teams to scale individual services independently, reducing infrastructure costs for components with uneven load." ] } ] } } ``` Use `research_effort` to control how deep the API digs — `lite` for quick answers, `standard` for a good balance, `deep` or `exhaustive` when thoroughness matters more than speed. [Full Research API reference and all parameters](/docs/research/overview) *** ## More ways to explore ### Explore the APIs interactively right here in the docs * [Search API playground](/docs/api-reference/search/v1-search?explorer=true) * [Contents API playground](/docs/api-reference/contents?explorer=true) * [Research API playground](/docs/api-reference/research/v1-research?explorer=true) ### Use the SDKs Benefit from ergonomic API access, type safety and easy readability. * [Python SDK](/docs/sdks/python-sdk) * [TypeScript SDK](/docs/sdks/typescript-sdk) ### Try in Postman Fork one of our pre-built collections, add your API key to the `production` environment, and send your first request without writing any code. ### Use a coding agent to write your integration There are 2 easy ways to create context for your agent: 1. Add `/llms-full.txt` to any URL path on this site to obtain the full content of a page in plain-text. For example, `docs.you.com/llms-full.txt` contains complete documentation content including the full text of all pages. This includes the complete API reference, complete with raw OpenAPI specs and SDK code examples. 2. Enable your agent to automatically discover and understand You.com APIs using our documentation-specific MCP server. Simply add the following wherever you store your MCP config: ```json "docs.you.com": { "name": "docs.you.com", "url": "https://docs.you.com/_mcp/server", "headers": {} } ``` Now your agent can automatically search the entirety of the You.com documentation as necessary. *** ## Evaluate You.com You're now ready to evaluate. You.com provides an [open-source evaluation framework](https://github.com/youdotcom-oss/evals) and a trustworthy, reproducible methodology for benchmarking search APIs — so you can measure what actually matters: accuracy, latency, and information retrieval quality. We're the only search API provider with peer-reviewed evaluation research. Our methodology was presented at the Association for the Advancement of Artificial Intelligence (AAAI) 2026 conference and received the Best Paper Award — meaning the way we think about search evals has been independently validated by the research community. To read more about our research please read these articles: 1. [Stochasticity in Agentic Evaluations: Quantifying Inconsistency with Intraclass Correlation](https://arxiv.org/abs/2512.06710) 2. [Randomness in AI Benchmarks: What Makes an Eval Trustworthy?](https://you.com/resources/randomness-in-ai-benchmarks) The open-source framework treats each search provider as a sampler: for every query, results are fetched from the API, synthesized into an answer by an LLM, then graded against ground truth. It supports various search providers giving you an apples-to-apples comparison on several benchmarks like: * SimpleQA — factual question answering * FRAMES — deep research and multi-hop reasoning * Latency profiling — end-to-end measurement under real conditions When starting your own evaluation, keep it simple: run count=10 with no filters on a representative query set, then layer in livecrawl if snippets aren't providing enough context. The resources below take you further: * [How to Evaluate the Search API](/docs/evaluate-us) — methodology, dataset recommendations (SimpleQA, FRAMES, FreshQA), latency benchmarking, and a production checklist * [Agentic Web Search Playoffs](https://github.com/youdotcom-oss/agentic-web-search-playoffs) — open-source benchmark comparing web search providers in agentic workflows Our team can also design and run custom benchmarks tailored to your domain and quality bar. [Talk to us](https://you.com/evaluations-as-a-service) *** ## Use cases Ready-to-run sample apps built on You.com APIs. Each comes with a live demo and a fully forkable open-source GitHub repo — clone it, extend it, or use it as a starting point for your own project. Runs a web search and returns the top results. Ask questions about your private documents. In-depth research with grounded answers and inline citations. *** ## Pricing You.com uses pay-as-you-go pricing based on the API and usage. All new accounts include **\$100 in free credits**. ### Quick pricing overview * **Search API**: \$5.00 per 1,000 calls * **Contents API**: \$1.00 per 1,000 pages * **Research API**: Starts at \$12 per 1,000 calls (varies per effort tier) Track your usage and spending from the [analytics dashboard](https://you.com/platform/analytics). For volume discounts, annual pricing, and enterprise features, visit [you.com/pricing](https://you.com/pricing) or contact [api@you.com](mailto:api@you.com).