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

# Changelog

## October 9, 2026

## Highlight Token Budget for POST /v1/search

`extraction_mode: "highlights"` now accepts an optional `highlights` object with `total_max_tokens`, a cap on the number of highlight tokens across the whole response. It takes values from 1024 to 8192. Omit it and the default budget of 8192 applies, so existing requests are unaffected.

A 10-result highlights response is roughly 6,000–7,500 tokens by default. With `total_max_tokens: 1024` it drops to under 1,000, which suits agents that call search in a tight loop. The budget is shared by every result, so pair it with a lower `count` when you want fewer, longer results.

Read the Retrieve Page Content guide

## October 7, 2026

## Structured Output for the Finance Research API

`POST /v1/finance_research` now accepts `output_schema`. Send a JSON Schema and `output.content` comes back as a JSON object that matches it, with `output.content_type` set to `object`. Sources stay in `output.sources`.

The schema rules and limits are the same as the Research API's: object root, `additionalProperties: false` on every object, every property in `required`, nesting depth up to 5, and up to 100 properties. A schema that works on `POST /v1/research` works here unchanged. Unlike the Research API, `output_schema` works with every Finance Research API effort level.

Requests without `output_schema` are unaffected and still return a Markdown answer.

Read the Structured Output guide

## October 5, 2026

## Spending Caps on API Keys

You can now set a spending cap on any API key. The cap is a dollar limit on what that key can spend in a billing period, and it applies to that key alone, so a development key or an unattended agent can't draw down the credits the rest of your organization depends on.

Set a cap when you create a key, or add, change, or remove one from the key's options menu on the [API Keys page](https://you.com/platform/api-keys). The keys table shows each capped key's spend for the current billing period next to its cap.

* Owners and Admins can set caps on any key in the organization. Developers can set caps on the keys they created.
* Keys without a cap behave exactly as before.
* When a key reaches its cap, its requests return `429` with the `spend_cap_exceeded` error code.

Read the docs

## September 23, 2026

## Knowledge for POST /v1/search

`POST /v1/search` now accepts `"knowledge": "core"`, which queries licensed data providers in parallel with the web index and returns matching records in `results.knowledge`. Coverage spans stocks, prices and rates, macroeconomics, company data, sports, politics and government, and weather and climate.

Each knowledge result carries a `title`, a `description` holding the value, an `attribution` array naming the data provider, and an optional `as_of` date. Up to 25 results come back, limited to those relevant to the query. When none are relevant, `results.knowledge` is omitted and the response contains web and news results only.

On the [VerticalRTK fast set](https://github.com/TakoData/VerticalRTK/blob/main/data/verticalrtk_fast.jsonl) benchmark, accuracy rose from 64.5% (Web Search API with highlights) to 84.2% (with highlights and Knowledge).

Knowledge is included in the base Web Search API rate of \$5.00 per 1,000 calls. It is available on `POST /v1/search` only, and existing requests are unaffected until they set the parameter.

Read the Knowledge guide

## September 2, 2026

## Extraction Source for POST /v1/search

The `extraction` object on `POST /v1/search` now accepts an `extraction_source` field that controls where full page content comes from:

* **`blend`** serves cached content when it is available and crawls the page live when it is not. This is the default, so existing requests are unaffected.
* **`cache`** returns cached content only. It is the fastest of the three because it never waits on a crawl, and results with nothing cached come back without a `contents` object.
* **`fetch`** always crawls the page live, which returns the freshest content at higher latency.

`extraction_source` applies to `extraction_mode: "full_page"` and is ignored for `"highlights"`. It is available on `POST /v1/search` only.

Only pages crawled live are billed, at \$1.00 per 1,000 pages. Cached content carries no extraction charge, so `cache` costs nothing beyond the base call price and `blend` bills only the pages it crawls live.

Read the page content guide

## August 11, 2026

## Extraction Parameter for POST /v1/search

`POST /v1/search` now accepts an `extraction` object that controls what text comes back with each result. Two modes are available:

* **`extraction_mode: "highlights"`** returns `contents.highlights`—the passages from each page most relevant to your query, sized for token-sensitive agentic workflows. Snippets are omitted.
* **`extraction_mode: "full_page"`** returns `contents.markdown` or `contents.html` carrying the full page, alongside the default snippets.

The `extraction` parameter is available on `POST /v1/search` only. `GET /v1/search` continues to support `livecrawl` for full page content. Set `extraction.full_page.extraction_formats` to `["markdown"]`, `["html"]`, or both.

Full page extraction is billed at \$1.00 per 1,000 pages on top of the base Web Search API rate.

Read the Web Search API overview

## August 5, 2026

## Answer API for Cited Answers from a Single Query

The Answer API (`POST /v1/answer`) returns a synthesized, citation-backed answer to a question in one call. It retrieves web results from a single search, verifies citations against the source text, and returns a Markdown answer with inline citations — no orchestrating retrieval, page reads, prompts, or model selection on your end. It is designed to be focused and fast.

There are no effort tiers to tune, so latency and cost stay predictable across queries. On SimpleQA, the Answer API reports 93.48% accuracy at a p50 of 2.67 seconds, priced at \$5.00 per 1,000 calls.

It accepts the same search controls as the Web Search API — `freshness`, `country`, `language`, `include_domains`, `exclude_domains`, and `boost_domains` — and every response includes the `answer`, the `citations` with verbatim `excerpts`, and the web `results` considered during synthesis.

Read the Answer API guide

## August 4, 2026

## Machine Payments for the Web Search and Finance Research APIs

`GET /v1/search` and `POST /v1/finance_research` now accept machine payments, so an agent with a funded wallet can call either one without an API key, an account, or a prepaid credit balance. Payment settles inside the same HTTP exchange that requests the data.

Two protocols are advertised on both routes, and a single unpaid request returns terms for each:

| Endpoint                       | x402, USDC on Base or Solana | MPP, USDC on Tempo |
| ------------------------------ | ---------------------------- | ------------------ |
| Web Search                     | \$0.005                      | \$0.01             |
| Finance Research, `deep`       | \$0.11                       | \$0.11             |
| Finance Research, `exhaustive` | \$0.50                       | \$0.50             |

Both protocols match the standard credit prices. They diverge on Web Search only, because MPP settles through Stripe, where one cent is the smallest chargeable amount, so a half-cent call rounds up. Adding `livecrawl` raises the Web Search quote by \$0.001 per result on both protocols.

Watch the HTTP method. Each endpoint offers terms on one verb, and the other returns `401` — Web Search on GET, Finance Research on POST. [Zero Data Retention](/docs/administration/zero-data-retention) does not apply to keyless requests, since it is enforced against a specific organization's API keys and these requests carry no account.

Read the machine payments overview

## Machine Payments on /v1/agents/search

The agent search endpoint, `/v1/agents/search`, accepts machine payments on both GET and POST, with the same pricing as `/v1/search`. Send a payment header to trigger the `402` challenge and settle the call through [x402](/docs/administration/machine-payments/x402) or [MPP](/docs/administration/machine-payments/mpp).

x402 gating is endpoint-scoped, not method-scoped: when x402 is enabled for an endpoint, it is available on every method that endpoint offers for machine payments. That is why `/v1/agents/search` accepts x402 on both verbs while `/v1/search` accepts it on GET only.

The full endpoint and method table is on the [Machine Payments overview](/docs/administration/machine-payments#supported-endpoints).

Read the machine payments overview

## July 20, 2026

## Background Mode for Long-Running Research Tasks

The Research API now supports a `background` parameter on `POST /v1/research`. Set `background: true` to queue the request as an asynchronous task and receive a task handle immediately, instead of waiting for the final answer inline. Poll `GET /v1/research/{task_id}` for status and results, or stream real-time progress via `GET /v1/research/{task_id}/stream` using Server-Sent Events.

Background mode works with `deep`, `exhaustive`, and `frontier` effort levels. It's the recommended approach when research may exceed client-side timeouts.

Read the background mode guide

## New `frontier` Research Effort Level

A new `frontier` effort level is available for long-running, deep research tasks that require the maximum compute budget. Frontier is priced at \$1,200 per 1k requests, with latency ranging from 30s to 12000s (p50: 300s).

Frontier requires `background: true` — synchronous requests with `research_effort: "frontier"` return `422`. Structured output via `output_schema` is supported.

View the effort levels table

## July 15, 2026

## Removed `authors` Field from Web Search API and Answer API Responses

The `authors` field is no longer included in Web Search API v1 search results or Answer API source results. The field has been removed from both response schemas and all related documentation. The v0 (legacy) search API was not affected, as it did not include this field.

Review the updated response schemas in the [Web Search API guide](/docs/guides/search) and the [Answer API reference](/docs/api-reference/answer/v1-answer).

View the Web Search API reference