> 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 (free Search only: `?profile=free`). 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`.

# Web Search API Quickstart

The Web Search API returns real-time web and news results as structured, LLM-ready JSON. Feed the results into your prompt to ground a model in fresh information.

Get an API key at [you.com/platform](https://you.com/platform). New accounts start with \$100 in complimentary credits. The samples below read `YDC_API_KEY`. See the [site Quickstart](/docs/quickstart) for the five-API tour and [API key management](/docs/administration/api-keys) for best practices.

```python
from youdotcom import You

with You() as you:
    results = you.search(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: process.env.YDC_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 -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "global birth rate trends",
    "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",
        "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
  }
}
```

The [Python SDK](/docs/sdks/python-sdk) covers the Web Search, Answer, Contents, Research, and Finance Research APIs. The [TypeScript SDK](/docs/sdks/typescript-sdk) covers the Web Search, Contents, and Research APIs. Call Answer and Finance Research over HTTP with the same `X-API-Key` header.

## Add Full Page Content

Search results already include snippets. Use `extraction` with `extraction_mode: "full_page"` to attach clean Markdown or HTML for each result. See [Retrieve page content](/docs/guides/search/retrieve-page-content) for highlights, cache vs. live crawl, and pricing.

```python
from youdotcom import You
from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode

with You() as you:
    results = you.search(
        query="global birth rate trends",
        count=5,
        extraction=Extraction(
            extraction_mode=ExtractionMode.FULL_PAGE,
            full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]},
        ),
    )

    for result in results.results.web:
        if result.contents and result.contents.markdown:
            print(result.title)
            print(result.contents.markdown[:400])
```

```typescript
import { You } from "@youdotcom-oss/sdk";
import { ExtractionFormat, ExtractionMode } from "@youdotcom-oss/sdk/models";

const you = new You({ apiKeyAuth: process.env.YDC_API_KEY });

const result = await you.search({
  query: "global birth rate trends",
  count: 5,
  extraction: {
    extraction_mode: ExtractionMode.FullPage,
    full_page: { extraction_formats: [ExtractionFormat.Markdown] },
  },
});

result.results?.web?.forEach((r) => {
  if (r.contents?.markdown) {
    console.log(r.title);
    console.log(r.contents.markdown.slice(0, 400));
  }
});
```

```curl
curl -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "global birth rate trends",
    "count": 5,
    "extraction": {
      "extraction_mode": "full_page",
      "full_page": {
        "extraction_formats": ["markdown"]
      }
    }
  }'
```

#### [Try in Postman](https://www.postman.com/youdotcom/you-com-api-workspace/collection/46015159-83118dc1-7279-49f6-893d-4c18b8163008)

Fork the Web Search API collection, add your API key to the `production` environment, and hit Send.

## Next Steps

#### [Web Search API Overview](/docs/guides/search)

How the API works, what you get, pricing, and when to use each feature

#### [Retrieve page content](/docs/guides/search/retrieve-page-content)

Highlights vs. full page content, extraction source, and crawl timeout

#### [API reference](/docs/api-reference/search/v1-search)

Full parameter reference, request/response schemas, and playground

#### [Site Quickstart](/docs/quickstart)

Try Answer, Contents, Research, and Finance Research in one tour