Quickstart

Get Your API Key

Sign in or create an account, then get an API key here: https://you.com/platform.

Each API has its own endpoint. Every request sends your API key in the X-API-Key header.

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.

Try the Web Search API

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

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)
        highlights = result.contents.highlights if result.contents else None
        if highlights:
            print(highlights[0])

The Python sample follows the SDK default and prints contents.highlights. The TypeScript and curl calls omit extraction, so raw POST /v1/search returns snippets. you.search() in the Python SDK 3.6.0 and later sends knowledge="core" and extraction={"extraction_mode": "highlights"} when you pass neither argument, and snippets is None. Knowledge adds no extra charge. See Billing.

Pass both arguments as None for snippets:

results = you.search(
    query="global birth rate trends",
    count=5,
    knowledge=None,
    extraction=None,
)

Highlights accepts count up to 50. The SDK default uses highlights, so a count above 50 needs extraction=None or extraction_mode set to full_page.

A raw POST /v1/search call returns JSON like this:

{
  "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
  }
}

Ground a Model with Highlights

Snippets are the HTTP default. Raw POST /v1/search returns them when the body omits extraction. The Python SDK 3.6.0 and later defaults to highlights and knowledge="core", so you.search() returns contents.highlights and snippets is None. Pass knowledge=None and extraction=None for snippets. The sample sets extraction_mode to highlights, which is what an HTTP client sends for the same excerpts.

from youdotcom import You
from youdotcom.models import Extraction, ExtractionMode
with You() as you:
    results = you.search(
        query="global birth rate trends",
        count=5,
        extraction=Extraction(
            extraction_mode=ExtractionMode.HIGHLIGHTS,
        ),
    )
    if results.results and results.results.web:
        for result in results.results.web:
            if result.contents and result.contents.highlights:
                print(result.title)
                print(result.contents.highlights[0])

See Retrieve page content for the token budget, knowledge: "core" for live licensed data, and pricing.

Improve Accuracy with Full Page Extraction

Search results already include query-relevant text extracts from target pages. Use the extraction parameter with extraction_mode: "full_page" to fetch full page content for each result as clean Markdown or HTML.

This will naturally increase latency, but massively improves knowledge accuracy.

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])

Results that support extraction will include a contents.markdown field with the full page. For RAG pipelines that need deep context rather than highlights excerpts, this is the parameter to reach for.

Web Search API Quickstart · Overview

Try the Answer API

The Web Search API gives you the raw results. The Answer API does the next step—it retrieves web results, verifies every citation against the source text, and returns a Markdown answer with inline citations in one call. The fastest path from a question to a grounded answer, with no orchestration on your end.

from youdotcom import You
with You() as you:
    response = you.answer(
        query="What are the main drivers of the global decline in birth rates?",
    )
    print(response.answer)
    print(f"\n--- {len(response.citations or [])} citations ---")
    for i, citation in enumerate(response.citations or [], 1):
        print(f"[{i}] {citation.source}")

The response includes a Markdown answer with numbered inline citations, the sources cited, and the web results considered during synthesis:

{
  "answer": "Global fertility rates have declined over the past five decades due to a combination of increased access to contraception, rising female education and labor force participation, higher costs of raising children, and urbanization. [[1, 2, 3]]",
  "citations": [
    {
      "source": "https://www.worldbank.org/en/topic/population",
      "excerpts": [
        "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."
      ]
    }
  ],
  "results": {
    "web": [
      {
        "url": "https://www.worldbank.org/en/topic/population",
        "title": "Population | World Bank",
        "snippets": ["Global fertility rates have declined significantly over the past five decades..."]
      }
    ]
  }
}

Every citation is verified against the source text before the answer is returned—the excerpts are the verbatim passages the model used, so you can confirm accuracy without trusting the model alone. Use freshness, country, language, include_domains, exclude_domains, and boost_domains to steer results, same as the Web Search API.

Answer API Quickstart · Overview

Try the Contents API

The Contents API fetches content from URLs you specify as clean Markdown or HTML—no browser automation, no HTML parsing. One use: pass your competitors’ pricing page URLs to a daily job and feed the Markdown to an LLM to monitor what changed.

from youdotcom import You
from youdotcom.models import ContentsFormats
with You() as you:
    pages = you.contents(
        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)

Each URL comes back as a structured object:

[
  {
    "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"
    }
  }
]

Contents API Quickstart · 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—so you don’t have to. Control the depth with research_effort from lite to frontier.

from youdotcom import You
from youdotcom.models import ResearchEffort
you = You()
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}")

The response includes a Markdown-formatted answer with inline citations and the list of sources used:

{
  "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, or frontier for long-running deep research that requires background requests. The Research API also supports source control and structured output for domain filtering and structured JSON output.

Research API Quickstart · Overview

Try the Finance Research API

The Finance Research API works just like the Research API—same request shape, same response shape—but it searches a finance-optimized index instead of the open web: SEC filings, equity prices, fundamentals, macro indicators, and financial news. Use it for earnings analysis, due diligence, and market research.

It accepts two parameters: input (your financial question) and research_effort (deep or exhaustive).

from youdotcom import You
from youdotcom.models import FinanceResearchEffort
with You() as you:
    res = you.finance_research(
        input="What were the key drivers of NVIDIA's revenue growth in fiscal year 2025?",
        research_effort=FinanceResearchEffort.DEEP,
    )
    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}")

The response is the same shape as the Research API—a Markdown answer with inline citations and a list of sources, but every source comes from the financial index:

{
  "output": {
    "content": "For fiscal year 2025, NVIDIA's revenue rose to **$130.5 billion, up 114% year over year**.[[1]] The main driver was Data Center demand...",
    "content_type": "text",
    "sources": [
      {
        "url": "https://investor.nvidia.com/financial-info/financial-reports/default.aspx",
        "title": "NVIDIA Corporation - Financial Reports"
      }
    ]
  }
}

The Finance Research API does not support source_control. If you need domain filtering, use the Research API. For structured JSON output, add an output_schema.

Finance Research API Quickstart · Overview