---
source_url: "https://you.com/docs/sdks/python-sdk"
title: "Python SDK | You.com | You.com | Documentation"
mirrored_at: 2026-08-20T13:02:22.357Z
host: you.com
cited_in_42a: true
mirror_canonical: "https://index.42a.ai/you.com/docs/sdks/python-sdk"
---

> **Original source:** https://you.com/docs/sdks/python-sdk

We offer a Python SDK to make interacting with our APIs simple and predictable. It covers the Web Search, Answer, Contents, Research, and Finance Research APIs, and is available on PyPI [here](https://pypi.org/project/youdotcom/). Now you can get started with our APIs with just a few lines of code.

##### Install our docs MCP server

This documentation ships with a Docs MCP Server that gives any MCP-enabled agent a `searchDocs` tool to search every page here and get back relevant passages with source URLs—no API key required. Point your client at `https://you.com/docs/_mcp/server`. See the [Docs MCP Server guide](https://you.com/docs/build-with-agents/docs-mcp-server) for setup and examples.

## Quickstart

[2](https://you.com/docs/sdks/python-sdk#install-the-sdk)

### Install the SDK

$

pip install youdotcom

[3](https://you.com/docs/sdks/python-sdk#run-a-search)

### Run a Search

Perform a simple search to retrieve results from general web and news sources.

1

from youdotcom import You

2

3

\# Initialize the SDK — it reads your key from YDC\_API\_KEY

4

you \= You()

5

6

\# Perform a search

7

results \= you.search(

8

    query\="latest AI developments"

9

)

10

11

\# Access the results

12

print(results)

That’s it. You now have a comprehensive set of search results combining web and news sources.

## What’s next?

The Web Search API offers filters that can help you find exactly what you need, whether you want to go broader or narrower. For example, to find recent information in the United States about renewable energy from the past week limited to 10 results per source type, either `web` or `news`, write:

1

from youdotcom import You

2

from youdotcom.models import Freshness, Country

3

4

with You() as you:

5

    results \= you.search(

6

        query\="renewable energy",

7

        count\=10,

8

        freshness\=Freshness.WEEK,

9

        country\=Country.US,

10

    )

Learn more about the Web Search API in the [Web Search API reference](https://you.com/docs/api-reference/search/v1-search), and the Python SDK by visiting the open source repository on [GitHub](https://github.com/youdotcom-oss/youdotcom-python-sdk/).

## Response Structure

The Web Search API returns a `SearchResponse` object (see [documentation](https://github.com/youdotcom-oss/youdotcom-python-sdk/blob/main/docs/models/searchresponse.md)):

###### results.web

An array of web result objects. Each object may include `url`, `title`, `description`, `snippets`, `thumbnail_url`, `page_age`, and `favicon_url`.

###### results.news

An array of news article objects. Each object may include `url`, `title`, `description`, `thumbnail_url`, and `page_age`.

###### metadata

Information about the search query and response, including `query`, `search_uuid`, and `latency`.

## Long-Running Research

Research at `deep`, `exhaustive`, or `frontier` effort can run for minutes, which is long enough to exceed a client timeout or tie up a worker. Run those in background mode and let the SDK handle the task lifecycle. The helpers live in `youdotcom.research_helpers`, which is a separate import from the client itself.

1

from youdotcom import You

2

from youdotcom.models import ResearchEffort

3

from youdotcom.research\_helpers import research\_and\_wait

4

5

with You() as you:

6

    task \= research\_and\_wait(

7

        you,

8

        input\="Which global cities improved air quality the most over the past 10 years?",

9

        research\_effort\=ResearchEffort.FRONTIER,

10

        timeout\_s\=600,

11

    )

12

    print(task.status)

13

    print(task.result.output\["content"\])

Pick the helper that matches how your code is shaped:

Helper

Use it when

`research_and_wait(client, **kwargs)`

You want one blocking call and only care about the final result.

`research_background(client, **kwargs)`

You want the task handle immediately—returns `task_id` and `stream_url`.

`poll_research_task(client, task_id)`

You already have a `task_id`, possibly from another process, and want to wait for it.

`stream_research(client, task_id)`

You want progress events as they happen. Yields `id`, `event`, and `data`.

Every helper has an `_async` counterpart (`research_and_wait_async`, `poll_research_task_async`, `stream_research_async`, `research_background_async`) for use with `asyncio`.

For the full background task lifecycle, including the raw endpoints behind these helpers, see the [Research API guide](https://you.com/docs/guides/research).

## Error Handling

Always handle potential errors when making API requests:

1

from youdotcom import You, errors

2

3

try:

4

    with You() as you:

5

        results \= you.search(query\="your query")

6

        print(results)

7

except errors.YouError as e:

8

    print(f"Search failed: {e.message}")

9

    print(f"Status code: {e.status\_code}")

## Learn More