> 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`. # Research API > Web Search, Answer, Contents, Research, and Finance Research APIs that give your AI app real-time web intelligence. Start with free credits. ## Docs - [Research API Quickstart](https://you.com/docs/guides/research/quickstart.md): Send a question to the Research API and get a Markdown answer with inline citations. Control depth with research_effort. - [Background Requests](https://you.com/docs/guides/research/background-requests.md): Set background: true on the Research API to run the request asynchronously. Poll or stream the task for the final result. - [Structured Output](https://you.com/docs/guides/research/structured-output.md): Use output_schema on the Research API to return output.content as a JSON object that follows a supported JSON Schema subset. - [Source Control](https://you.com/docs/guides/research/source-control.md): Use source_control to filter Research API sources by domain, freshness, and country. > **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`. # Research 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 Research API? The Research API returns grounded, natural language answers to questions of varying complexity. It runs multiple searches, processes the results, cross-references sources, and synthesizes everything into a thorough, Markdown-formatted answer with inline citations. When you need a typed response, you can also get structured JSON by defining an `output_schema`. Ask a hard question, get a researched answer with sources. --- ## 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's Different From Search The Web Search API and the Research API serve different purposes by delivering different outputs: | | Web Search API | Research API | | -------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Input** | Query, several search parameters (count, language, extraction etc.) | Query, research effort, source controls, optional output schema | | **You get** | Raw search results (URLs, snippets, metadata) | A natural language answer or structured JSON object with inline citations, plus search results | | **Processing** | Returns results as-is for you to process | Reads, reasons over, and synthesizes results for you | | **Speed** | Fast—single search round trip | Varies—multiple searches and reasoning steps | | **Control** | Full control over how results are used | Control depth, sources, recency, geography, and response shape | | **Best for** | RAG pipelines, building your own search UI, data gathering | Answering questions of varying complexity using multiple sources | Use the Web Search API when you want raw results to feed into your own pipeline. Use the Research API when you want a ready-to-use answer backed by sources. If the job is a single-pass cited answer, known URLs, or a finance-optimized index, [Choose the Right API](/docs/choose-the-right-api) maps those jobs to the Answer API, Contents API, and Finance Research API. --- ## How It Works Research operates as an agentic system that autonomously plans and executes a multi-step research strategy for your question. ### Search, Contents, and Live News as retrieval primitives Research uses You.com's Search, Contents, and Live News APIs as its core tools. Rather than firing generic web queries, the system selects the right tool for each sub-question—search for discovery, contents for deep page reads, live news for time-sensitive information, and several other internal tools to aid in generating the best possible answer. This targeted tool selection reduces wasted calls and gives the reasoning model cleaner inputs at each step. The system also evaluates retrieved sources for freshness, diversity, and relevance before incorporating them into the answer. ### Context management at scale Deep research generates far more information than any single LLM context window can hold. Research uses context-masking and compaction strategies that let it operate well beyond those limits—maintaining coherent reasoning across hundreds or thousands of turns without losing track of what it found, what it verified, and what remains unresolved. At higher effort levels, a single query can run more than 1,000 reasoning turns and process up to 10 million tokens. ### Budget-based planning The system receives a compute budget determined by the `research_effort` tier you choose. It plans its approach around that budget, allocating more effort to verifying ambiguous or high-stakes claims and moving quickly through well-sourced facts. This is the mechanism that enables the range of latency, accuracy, and cost tradeoffs across tiers. --- ## What You Get Every Research API response includes: * **`content`**: A Markdown-formatted answer by default, or a JSON object when you provide `output_schema`. Inline citations such as `[[1, 2]]` reference items in the `sources` array. * **`content_type`**: The format of the content field. `text` is returned for default Markdown responses. `object` is returned for structured output. * **`sources`**: The web pages the API read and cited in the answer—each with a URL, title, and relevant snippets. ```json maxLines=25 { "output": { "content": "## RISC-V vs ARM: Key Architectural Differences\n\nRISC-V and ARM are both reduced instruction set architectures, but they differ in licensing, extensibility, and ecosystem maturity [[1, 2]].\n\n### Licensing\nARM requires per-chip licensing fees, while RISC-V is open-source and royalty-free [[1, 3]]...", "content_type": "text", "sources": [ { "url": "https://example.com/risc-v-vs-arm", "title": "RISC-V vs ARM: A Technical Comparison", "snippets": [ "RISC-V's open ISA allows custom extensions without licensing negotiations, making it attractive for specialized hardware." ] }, { "url": "https://example.com/processor-architectures", "title": "Modern Processor Architectures Explained", "snippets": [ "ARM's mature ecosystem includes extensive tooling and vendor support built over three decades." ] } ] } } ``` --- ## Features ### Research effort levels The `research_effort` parameter controls how much compute the API allocates to your question. Higher effort means more searches, deeper source reading, and more cross-referencing—at the cost of longer response times. | Tier | Price per 1k | Latency | Use case | | ------------ | ------------ | --------------------------------------- | -------------------------------------------------------------- | | `lite` | \$12 | \< 10s | Quick factual lookups, simple searches | | `standard` | \$50 | \~10–30s | Balanced depth for most production use (default) | | `deep` | \$100 | \< 120s | Complex multi-source research and synthesis | | `exhaustive` | \$450 | \< 300s | Comprehensive analysis across dozens of sources | | `frontier` | \$1,200 | Background only. 30s–12000s (p50: 300s) | Long-running deep research tasks. Requires `background: true`. | A synchronous request holds the connection for the full run. Set your HTTP client timeout above the tier's upper bound—longer than 120s for `deep` and 300s for `exhaustive`—or send `background: true` and collect the result with [background requests](/docs/guides/research/background-requests). For the same query, the difference between tiers is substantial. Here's an abridged comparison for the question *"Which global cities improved air quality the most over the past 10 years, and what measurable actions contributed?"*: #### research_effort = standard ```json maxLines=40 wordWrap { "output": { "content": "Global assessments show that the largest recent urban air-quality improvements are concentrated in East China, parts of the eastern United States, Europe, and Japan, with especially strong gains in Chinese megacities and cities with aggressive traffic-emissions controls such as London [[1, 2, 3]].\n\n1) Beijing (China) — PM2.5 fell from ~89–90 µg/m³ in 2013 to ~58 µg/m³ in 2017 (about 35–36% in five years), with evidence from both satellite and surface observations [[4, 5]].\nKey drivers included coal phase-down, industrial controls, stricter vehicle/fuel standards, and regional enforcement [[6, 7, 8]].\n\n2) Chinese city clusters (BTH / YRD / PRD) — China's population-weighted PM2.5 fell ~32% from 2013–2017, with the largest modeled decline in Beijing–Tianjin–Hebei (~38%); across 367 cities, observed PM2.5 fell ~44% from 2013–2019 [[9, 10]].\nThe main drivers were national clean-air action plans, coal controls, industrial restructuring, and transport emissions standards [[7, 9, 10]].\n\n3) London (UK) — London achieved major NO2 reductions linked to LEZ/ULEZ policies, with monitoring and modeling studies showing accelerated declines after ULEZ implementation and meaningful reductions versus no-ULEZ scenarios [[11, 12, 13, 14]].", "content_type": "text", "sources": [ { "url": "https://pubmed.ncbi.nlm.nih.gov/36356738/", "title": "Trends in urban air pollution over the last two decades: A global perspective - PubMed", "snippets": [ "At global scale, PM2.5 exposures declined slightly from 2000 to 2019 ... Improvements were observed in the Eastern US, Europe, Southeast China, and Japan..." ] } ] } } ``` #### research_effort = exhaustive ```json maxLines=40 wordWrap { "output": { "content": "There is no single definitive \"top 10\" ranking, but several independent datasets and case studies point to a small group of cities — especially in China plus a few in Europe and North America — that have seen the largest, clearly measured air-quality gains in roughly the last decade. Below are the clearest examples where both (1) large, quantified reductions in PM2.5 or NO2 are documented and (2) specific policies can be tied to those improvements.\n\n1) Beijing (and other major Chinese cities)\nBeijing shows one of the strongest documented improvements globally. Annual mean PM2.5 fell from roughly 89–102 µg/m³ in 2013 to about 32–39 µg/m³ by 2023, implying an approximately 60–65% reduction over about a decade [[1, 2, 3, 4]]. National analyses also show large PM2.5 declines across hundreds of Chinese cities, and EPIC/AQLI attributes a major share of global PM2.5 reduction since 2013 to China's air-quality policies [[5, 6, 7]].\nThe key drivers were policy-led and multi-sector: coal-to-clean energy transition, coal boiler controls, industrial restructuring, tighter emissions standards, vehicle standards and scrappage, fuel quality improvements, and regional coordination across Beijing–Tianjin–Hebei [[8, 9, 10, 11, 12, 13]]. Atmospheric modeling indicates most of Beijing's 2013–2017 PM2.5 improvement was due to emissions reductions rather than weather variation [[2, 8]].\n\n2) Seoul metropolitan area (Seoul, Incheon, Gyeonggi)\nThe Seoul metropolitan region shows strong evidence of long-term emissions reductions tied to policy. Joint Seoul/UNEP assessments report very large reductions in fine particulate emissions (including about a 75% reduction in Seoul's emitted PM2.5 mass and substantial reductions in Gyeonggi) over 2005–2020 [[14]]. Additional studies indicate stricter vehicle-emissions regulations contributed to lower particulate concentrations in the 2010s compared with the 2000s [[15]], while UNEP reports national PM2.5 emissions declines with even greater reductions in Seoul and Gyeonggi [[16]].\nKey actions included tightening vehicle standards, replacing diesel buses with CNG buses, incentivizing after-treatment systems and cleaner vehicles, emissions-cap regulation and trading in the Seoul metropolitan area, fuel switching, and stronger industrial controls [[15, 17, 18, 19]]. Seoul still experiences episodic pollution due in part to transboundary transport, especially from upwind regions [[20, 21, 22]].\n\n3) London (ULEZ, LEZ, congestion charging)...", "content_type": "text", "sources": [ { "url": "https://sustainablemobility.iclei.org/air-pollution-beijing/", "title": "Clearing the skies: how Beijing tackled air pollution & what lies ahead - ICLEI Sustainable Mobility", "snippets": [ "China played a vital role, accounting for three-quarters of global air pollution reductions from 2013-2020...", "The annual average PM2.5 concentrations ... decreased..." ] } ] } } ``` The `exhaustive` response identifies additional cities (Seoul, with specific UNEP data), includes more granular measurements (µg/m³ ranges, percentage reductions over specific date ranges), and cross-references more sources to verify claims. ### Citation-backed answers Every claim in the response links back to a specific source via inline citations. Your users (or your system) can verify any statement by following the numbered references to the `sources` array. ### Markdown output The `content` field is formatted in Markdown with headers, lists, and inline citations—ready to render in a UI or feed into downstream processing. ### More capabilities | Feature | What it does | | ---------------------------------------------------------------- | ------------------------------------------------------------- | | [Source Control](/docs/guides/research/source-control) | Constrain domains, freshness, and country | | [Structured Output](/docs/guides/research/structured-output) | Return JSON that follows a schema instead of Markdown | | [Background Requests](/docs/guides/research/background-requests) | Queue long-running research and poll or stream for the result | --- ## Parameters | Parameter | Type | Required | Description | | ----------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `input` | string | Yes | The research question (max 40,000 characters) | | `research_effort` | string | No | Depth of research: `lite`, `standard` (default), `deep`, `exhaustive`, `frontier` | | `source_control` | object | No | Beta. Controls which sources the research agent can use through domain, freshness, and country filters. | | `output_schema` | object | No | Beta. Requests structured JSON output that follows a supported JSON Schema subset. Not available with `lite`. | | `background` | boolean | No | When `true`, runs the request asynchronously and returns a task handle. Poll or stream the task for the final result. | [View full API reference](/docs/api-reference/research/v1-research) --- ## Common Use Cases ### Complex question answering When a question can't be answered from a single source—comparative analyses, multi-factor evaluations, questions that span multiple domains—the Research API handles the synthesis for you. ***"Compare the pricing models of the top 3 vector databases and their tradeoffs for a 10M-document collection"*** ### Due diligence and market research Quickly gather verified, cited information about companies, markets, or technologies. The citation-backed output gives you traceability that raw LLM generation can't. ### Internal tools and knowledge assistants Build internal research tools where employees can ask complex questions and get sourced answers—product comparisons, regulatory summaries, technical deep dives—without manually reading dozens of pages. ### Content creation pipelines Use the Research API as the first step in a content pipeline: ask a research question, get a cited draft, then use it as source material for blog posts, reports, or briefings. --- ## Best Practices ### Match research effort to the question Don't use `exhaustive` or `frontier` for simple factual questions—`lite` or `standard` will be faster and cheaper. Save `deep`, `exhaustive`, and `frontier` for questions where thoroughness and accuracy justify the longer response time. ### Verify citations for high-stakes use cases The inline citations make verification straightforward. For legal, financial, or medical contexts, build a step that follows citation URLs to confirm claims before surfacing them to end users. ### Use structured inputs for better results The `input` field supports up to 40,000 characters. For complex research tasks, include context, constraints, or specific angles you want covered. A well-scoped question produces a more focused answer. ### Use background mode for long-running tasks For `deep` or `exhaustive` research that may exceed client-side timeouts, set `background: true` to queue the request and poll or stream for the result. This decouples submission from retrieval and keeps workers responsive when research takes minutes rather than seconds. The `frontier` effort level requires [background mode](/docs/guides/research/background-requests). --- ## Pricing Research API pricing is tiered by effort level. See the [Billing page](/docs/administration/billing#research-api) for complete pricing and latency by tier. Higher effort tiers allocate more compute for deeper reasoning, more source verification, and higher accuracy. See the [research effort levels table](#research-effort-levels) above for how each tier performs. 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). --- ## Try It #### [Research Agent template](/docs/examples/research) See a working agent that plans, searches, reads, and writes a cited report. --- ## Next Steps #### [Quickstart](/docs/guides/research/quickstart) Make your first Research API request #### [API Reference](/docs/api-reference/research/v1-research) Full parameter reference, request/response schemas and interactive playground #### [Background Requests](/docs/guides/research/background-requests) Queue long-running research and poll or stream for the result #### [Structured Output](/docs/guides/research/structured-output) Return JSON that follows a schema instead of Markdown