# Search overview
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://you.com/docs/search/llms.txt.
> For full documentation content, see https://you.com/docs/search/llms-full.txt.
## What is the You.com Search API?
The You.com Search API delivers high-quality, structured web and news results optimized for programmatic access in AI applications. Designed for developers building RAG systems, AI agents, knowledge bases, and data-driven applications, our Search API returns clean, structured data with rich metadata, relevant snippets, and full-page content.
## How it works
The Search API processes your query and returns unified results from both web and news sources in a single request. Each result includes:
1. **Core information**: URLs, titles, and descriptions
2. **LLM-ready snippets**: Query-aware text excerpts - the best snippets to answer your query will be provided
3. **Rich metadata**: Publication dates, authors, thumbnails, and favicons
4. **Full page content**: Live-crawled HTML or Markdown on demand
Our intelligent classification system automatically determines when to include news results based on query intent, ensuring you get the most relevant information for your use case.
## What you get
Every search returns structured JSON with two main result types:
**Web results**
* Relevant web pages from across the internet
* Multiple text snippets per result for context
* Publication dates and author information
* Thumbnail images and favicons for UI display
**News results** (when relevant)
* Recent news articles from authoritative sources
* Article summaries and headlines
* Publication timestamps for freshness
* Associated images and metadata
* Full article content (HTML or Markdown) via live crawling
All results are returned in clean, structured JSON format requiring no HTML parsing or post-processing.
***
## Key features
### Live crawling — full page content per result
With snippets alone, you get \~100–200 words of extracted text per result. With `livecrawl` enabled, you get the full page content—often 2,000–10,000 words of HTML or Markdown. This is what unlocks deep RAG, comprehensive synthesis, and knowledge base construction from search results.
Add `livecrawl` to any search request and each matching result gains a `contents` object with the full page content in your chosen format. Crawl `web`, `news` or `all` results.
Set `livecrawl_formats` to `markdown` (recommended for LLMs) or `html`.
```python startLine={5}
from youdotcom import You
from youdotcom.models import LiveCrawl, LiveCrawlFormats
with You(api_key_auth="api_key") as you:
# Livecrawl both web and news results
res = you.search.unified(
query="latest AI developments",
count=5,
livecrawl=LiveCrawl.ALL,
livecrawl_formats=LiveCrawlFormats.MARKDOWN,
)
# Access live-crawled content from web results
if res.results and res.results.web:
for result in res.results.web:
if result.contents:
print(f"Web: {result.title}")
print(f"Content: {result.contents.markdown[:200]}...\n")
# Access live-crawled content from news results
if res.results and res.results.news:
for result in res.results.news:
if result.contents:
print(f"News: {result.title}")
print(f"Content: {result.contents.markdown[:200]}...\n")
```
```typescript
import { You } from "@youdotcom-oss/sdk";
import { LiveCrawl, LiveCrawlFormats } from "@youdotcom-oss/sdk/models";
const you = new You({
apiKeyAuth: "api_key",
});
async function run() {
// Livecrawl both web and news results
const result = await you.search({
query: "latest AI developments",
count: 5,
livecrawl: LiveCrawl.All,
livecrawlFormats: LiveCrawlFormats.Markdown,
});
// Access live-crawled content from both web and news results
result.results?.web?.forEach((r) => {
if (r.contents?.markdown) {
console.log(`Web: ${r.title}`);
console.log(`Content: ${r.contents.markdown.slice(0, 200)}...\n`);
}
});
result.results?.news?.forEach((r) => {
if (r.contents?.markdown) {
console.log(`News: ${r.title}`);
console.log(`Content: ${r.contents.markdown.slice(0, 200)}...\n`);
}
});
}
run();
```
```curl
# Livecrawl both web and news results
curl -G https://ydc-index.io/v1/search \
-H "X-API-Key: api_key" \
--data-urlencode "query=latest AI developments" \
-d count=5 \
-d livecrawl=all \
-d livecrawl_formats=markdown
```
**Need content from specific URLs you already have?** Use the [Contents API](/docs/contents/overview) instead — it takes a list of URLs directly, without requiring a search query.
### Unified web & news results
Get both web pages and news articles in a single API call. Our classification system automatically determines when to include news results based on query intent.
```json maxLines=20
{
"results": {
"web": [ // Web search results
{
"url": "https://example.com/article",
"title": "Article Title",
"description": "Brief description of the content",
"snippets": [
"Relevant excerpt from the page",
"Another relevant passage"
],
"thumbnail_url": "https://example.com/image.jpg",
"page_age": "2025-11-15T10:30:00",
"authors": ["Author Name"],
"favicon_url": "https://example.com/favicon.ico",
"contents": { // Included when livecrawl is "web" or "all"
"markdown": "# Article Title\n\nFull page content..."
}
}
],
"news": [ // News articles (when relevant)
{
"title": "Breaking News Article",
"description": "News article summary",
"url": "https://news.com/article",
"page_age": "2025-11-15T14:00:00",
"thumbnail_url": "https://news.com/image.jpg",
"contents": { // Included when livecrawl is "news" or "all"
"markdown": "# Breaking News\n\nFull article content..."
}
}
]
},
"metadata": {
"search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90",
"query": "your search query",
"latency": 0.342
}
}
```
### LLM-optimized output
Every result includes:
* **Snippets:** Pre-extracted relevant text excerpts
* **Descriptions:** Clean summaries without HTML clutter
* **Metadata:** Publication dates, authors, thumbnails, favicons
* **Structured JSON:** No parsing required, ready for AI consumption
### Advanced search operators
Build powerful and precise search queries using search operators:
* `site:domain.com` - Search within specific domains
* `filetype:pdf` - Filter by file type
* `+term` / `-term` - Include/exclude specific terms
* Boolean operators: `AND`, `OR`, `NOT`
[Learn more about search operators](/docs/search/search-operators)
### Global coverage
Target results by geographic region using the `country` parameter (ISO 3166-2 country codes) and filter by language using the `language` parameter (BCP 47 language codes).
### Freshness controls
Filter results by recency:
* `day` - Last 24 hours
* `week` - Last 7 days
* `month` - Last 30 days
* `year` - Last 365 days
* `YYYY-MM-DDtoYYYY-MM-DD` - Custom date range
### All optional parameters you can control
| Parameter | Type | Description |
| ------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `query` | string | Your search query (supports [search operators](/docs/search/search-operators)) |
| `count` | integer | Max results per section (default varies, max 100) |
| `freshness` | string | `day`, `week`, `month`, `year`, or date range |
| `country` | string | Country code (e.g., `US`, `GB`, `FR`) |
| `language` | string | BCP 47 language code (e.g., `EN`, `JP`, `DE`) |
| `offset` | integer | For pagination (0-9) |
| `safesearch` | string | `off`, `moderate` (default), `strict` |
| `livecrawl` | string | `web`, `news`, or `all` |
| `livecrawl_formats` | string (GET) / array (POST) | `html` or `markdown`. GET: repeat the parameter (`?livecrawl_formats=html&livecrawl_formats=markdown`). POST: JSON array |
| `crawl_timeout` | integer | Maximum livecrawl timeout in seconds (`1-60`, default `10`). Applies only when `livecrawl` is enabled |
| `include_domains` | string (GET) / array (POST) | Restrict results to these domains. GET: comma-separated string. POST: JSON array. Supports up to 500 domains |
| `exclude_domains` | string (GET) / array (POST) | Exclude results from these domains. GET: comma-separated string. POST: JSON array. Supports up to 500 domains |
[View full API reference](/docs/api-reference/search/v1-search)
***
## Common use cases
### RAG (Retrieval-Augmented Generation)
Use search snippets to provide context to your LLM without hallucination. The structured snippets are perfect for feeding directly into your prompt.
See a working RAG app that lets users ask AI questions about their own private documents.
```python
from youdotcom import You
# Initialize
you = You("YOUR_KEY")
# Search and extract context
def get_context(query):
response = you.search.unified(query=query, count=5)
snippets = []
if response.results and response.results.web:
for result in response.results.web:
if result.snippets:
snippets.extend(result.snippets)
return "\n".join(snippets)
context = get_context("quantum computing")
# Feed to your LLM
prompt = f"Based on this information:\n{context}\n\nAnswer: {user_question}"
```
### AI agent knowledge retrieval
Give your AI agents access to real-time web information. Perfect for building agents that need up-to-date facts, news, or specialized domain knowledge.
See a working app that runs a web search and returns the top results.
### News monitoring & alerts
Track breaking news, competitor mentions, or industry trends. The automatic news classification ensures you get timely articles when relevant.
### Content research & analysis
Gather comprehensive information from multiple sources for content creation, competitive intelligence, or market research.
### Knowledge base construction
Use live crawling to build comprehensive knowledge bases with full-page content in clean Markdown format.
***
## Examples of advanced search capabilites
### Domain filtering
Restrict results to — or exclude results from — specific domains. For large domain lists, POST is strongly recommended.
```python
from youdotcom import You
with You(api_key_auth="api_key") as you:
# Only return results from trusted news sources
res = you.search.unified(
query="federal reserve interest rate decision",
include_domains=["reuters.com", "apnews.com", "ft.com", "bloomberg.com"],
)
if res.results and res.results.web:
for result in res.results.web:
print(f"{result.title} — {result.url}")
```
```typescript
import { You } from "@youdotcom-oss/sdk";
const you = new You({ apiKeyAuth: "api_key" });
async function run() {
// Only return results from trusted news sources
const result = await you.search({
query: "federal reserve interest rate decision",
includeDomains: ["reuters.com", "apnews.com", "ft.com", "bloomberg.com"],
});
result.results?.web?.forEach((r) => {
console.log(`${r.title} — ${r.url}`);
});
}
run();
```
```curl
# POST is recommended for domain lists — avoids URL length limits
curl -X POST https://ydc-index.io/v1/search \
-H "X-API-Key: api_key" \
-H "Content-Type: application/json" \
-d '{
"query": "federal reserve interest rate decision",
"include_domains": ["reuters.com", "apnews.com", "ft.com", "bloomberg.com"]
}'
```
### Search operators
Combine operators for powerful, precise searches:
```python
from youdotcom import You
from youdotcom.models import Freshness
with You(api_key_auth="api_key") as you:
# Find PDFs about climate change from .edu sites published this year
res = you.search.unified(
query="climate change site:.edu filetype:pdf",
freshness=Freshness.YEAR,
)
# Print PDF results with their URLs
if res.results and res.results.web:
for result in res.results.web:
print(f"{result.title}")
print(f" PDF URL: {result.url}")
```
```typescript
import { You } from "@youdotcom-oss/sdk";
import { Freshness } from "@youdotcom-oss/sdk/models";
const you = new You({
apiKeyAuth: "api_key",
});
async function run() {
// Find PDFs about climate change from .edu sites published this year
const result = await you.search({
query: "climate change site:.edu filetype:pdf",
freshness: Freshness.Year,
});
console.log(result);
}
run();
```
```curl
# Find PDFs about climate change from .edu sites published this year
curl -G 'https://ydc-index.io/v1/search' \
-H 'X-API-Key: api_key' \
--data-urlencode 'query=climate change site:.edu filetype:pdf' \
-d 'freshness=year'
```
### Pagination
Use `offset` to retrieve additional pages of results. The offset value (0-9) skips that many pages, so `offset=1` with `count=10` returns results 11-20.
```python
from youdotcom import You
with You(api_key_auth="api_key") as you:
# Get the second page of results
res = you.search.unified(
query="machine learning",
count=10,
offset=1,
)
print(res.results.web)
```
```typescript
import { You } from "@youdotcom-oss/sdk";
const you = new You({
apiKeyAuth: "api_key",
});
async function run() {
// Get the second page of results
const result = await you.search({
query: "machine learning",
count: 10,
offset: 1,
});
console.log(result);
}
run();
```
```curl
# Get the second page of results (results 11-20)
curl -G 'https://ydc-index.io/v1/search' \
-H 'X-API-Key: api_key' \
--data-urlencode 'query=machine learning' \
-d 'count=10' \
-d 'offset=1'
```
### Geographic targeting
Narrow down on results by country:
```python
from youdotcom import You
from youdotcom.models import Country
# Get Swiss results
with You(api_key_auth="api_key") as you:
res = you.search.unified(
query="best restaurants in geneva",
country=Country.CH,
)
# Print restaurant results with descriptions
if res.results and res.results.web:
for result in res.results.web:
print(f"{result.title}")
if result.description:
print(f" {result.description}\n")
```
```typescript
import { You } from "@youdotcom-oss/sdk";
import { Country } from "@youdotcom-oss/sdk/models";
const you = new You({
apiKeyAuth: "api_key",
});
async function run() {
// Get Swiss results
const result = await you.search({
query: "best restaurants in geneva",
country: Country.Ch,
});
console.log(result);
}
run();
```
```curl
# Get Swiss results
curl -G 'https://ydc-index.io/v1/search' \
-H 'X-API-Key: api_key' \
-d 'query=best restaurants in geneva' \
-d 'country=CH'
```
Refer to the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) standard for a list of country codes.
***
## Best practices
### 1. Use snippets for RAG
The `snippets` array is pre-processed for LLM consumption. Use it directly instead of crawling full pages when possible.
### 2. Implement caching
Cache frequent queries to reduce API calls and improve response times. Consider a 5-15 minute TTL for most use cases.
### 3. Handle empty results
Always check if `results.web` or `results.news` arrays are empty before processing:
```python
if results.get("results", {}).get("web"):
# Process results
else:
# Handle no results case
```
### 4. Use appropriate count values
* For RAG: `count=5-10` is usually sufficient
* For UI display: `count=20-50` for pagination
* For data gathering: `count=100` (max) for comprehensive coverage
### 5. Use search operators and query parameters
Use search operators and specify [query parameters](/docs/api-reference/search/v1-search#request.query) in the request to reduce noise and get more relevant results.
***
## GET vs. POST
The Search API supports both `GET /v1/search` and `POST /v1/search`. Both methods go through the same underlying logic and return identical responses — the difference is how parameters are encoded on the wire.
**Use GET when:**
* Your request only uses simple scalar parameters (`query`, `count`, `freshness`, etc.)
* HTTP cacheability matters — GET responses can be cached at CDN and proxy layers using the URL and `Vary: X-API-Key` as a cache key. POST responses are not cached by default per the HTTP spec.
* You want quick testing with curl or a browser.
**Use POST when:**
* You're using `include_domains` or `exclude_domains` — these accept JSON arrays in POST, supporting up to 500 domains. With GET, domains must fit in a single comma-separated query string value and are subject to URL length limits.
* Future array parameters work naturally as JSON — no ambiguity between comma-separated values and repeated params.
**Wire format differences for complex fields:**
| Field | GET | POST (JSON body) |
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------- |
| `include_domains` | `?include_domains=a.com,b.com` — comma-separated, single value | `"include_domains": ["a.com", "b.com"]` |
| `exclude_domains` | `?exclude_domains=a.com,b.com` — comma-separated, single value | `"exclude_domains": ["a.com", "b.com"]` |
| `livecrawl_formats` | `?livecrawl_formats=html&livecrawl_formats=markdown` — repeated params | `"livecrawl_formats": ["html", "markdown"]` |
GET domain filters do **not** support repeated parameters. `?include_domains=a.com&include_domains=b.com` will not work — only a single comma-separated value is supported. For large domain lists, use POST.
***
## Pricing
**\$5.00 per 1,000 calls**
All new accounts receive \$100 in free credits to get started. Pricing is simple — you only pay for what you use.
**What's included:**
* Web and news results in a single unified request
* Up to 100 results per call
* News results at no extra cost
* Full page content via livecrawl, as HTML, Markdown or both
* LLM-ready snippets with rich metadata
* Country, language, recency, domain and more targeting filters
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).
***
## Next steps
Use our Postman collections to learn and experiment on your own
Explore the complete API documentation with all parameters and response schemas
Master advanced search operators to refine your queries
Learn from practical examples and integration guides
Get your API key and make your first search in 5 minutes
***