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

# Background Requests

By default, `POST /v1/research` runs synchronously and blocks until the final answer is ready. For complex research at `deep` or `exhaustive` effort, that can exceed client-side timeouts or tie up a worker. Set `background: true` to run the request asynchronously and receive a task handle immediately. The `frontier` effort level requires background mode—synchronous requests with `research_effort: "frontier"` return `422`.

| Field        | Type      | Default | Description                                                                                           |
| :----------- | :-------- | :------ | :---------------------------------------------------------------------------------------------------- |
| `background` | `boolean` | `false` | When `true`, queues the request as a task and returns a handle immediately instead of waiting inline. |

In background mode, the response is a task object rather than the research result:

```json
{
  "task_id": "f1e2d3c4-0000-0000-0000-000000000000",
  "type": "research",
  "status": "queued",
  "stream_url": "/v1/research/f1e2d3c4-0000-0000-0000-000000000000/stream",
  "created_at": "2026-06-26T00:00:00Z"
}
```

A task moves through the following states: `queued` → `running` → `completed` | `failed` | `cancelled`.

## Poll for the Result

Call `GET /v1/research/{task_id}` to check status. The `result` field is `null` until the task completes. If the task fails, `status` is `failed` and `error` contains a diagnostic message.

```curl
curl "https://api.you.com/v1/research/{task_id}" \
  -H "X-API-Key: $YDC_API_KEY"
```

## Stream Progress

`GET /v1/research/{task_id}/stream` returns Server-Sent Events (SSE) with real-time progress. The stream starts with a `connected` event and closes when the task reaches a terminal status. Use `?from_id=N` to replay events after reconnecting. Once the stream closes, poll `GET /v1/research/{task_id}` to retrieve the full `result`.

```curl
curl "https://api.you.com/v1/research/{task_id}/stream" \
  -H "X-API-Key: $YDC_API_KEY"
```

## End-to-End Python Example

The Python SDK ships helpers for background tasks in `youdotcom.research_helpers`, so you do not have to write the submit-and-poll loop yourself. `research_and_wait()` submits the task, polls until it reaches a terminal status, and raises if it fails or times out.

```python
from youdotcom import You
from youdotcom.models import ResearchEffort
from youdotcom.research_helpers import research_and_wait

with You() as you:
    task = research_and_wait(
        you,
        input="Are 'Acme Logistics LLC' (Delaware) and 'Acme Logistics' (Newark, NJ) the same business?",
        research_effort=ResearchEffort.FRONTIER,
        output_schema={
            "type": "object",
            "properties": {
                "same_entity": {"type": "boolean"},
                "confidence": {"type": "number"},
                "evidence": {"type": "array", "items": {"type": "string"}},
            },
            "required": ["same_entity", "confidence", "evidence"],
            "additionalProperties": False,
        },
        timeout_s=600,
    )

    verdict = task.result.output["content"]
    print(f"Same entity: {verdict['same_entity']} (confidence: {verdict['confidence']})")
```

To submit and poll as separate steps—for example, when the task handle is stored and picked up by another worker—use `research_background()` and `poll_research_task()`:

```python
from youdotcom import You
from youdotcom.models import ResearchEffort
from youdotcom.research_helpers import poll_research_task, research_background

with You() as you:
    handle = research_background(
        you,
        input="Which global cities improved air quality the most over the past 10 years?",
        research_effort=ResearchEffort.FRONTIER,
    )
    print(f"Queued {handle.task_id}, stream at {handle.stream_url}")

    # ... later, in the same process or another one
    task = poll_research_task(you, handle.task_id, interval_s=5, timeout_s=600)
    print(task.status)
    print(task.result.output["content"])
```

To follow progress as it happens, `stream_research()` yields the Server-Sent Events described above. Each event carries an `id`, an `event` name, and a `data` payload, and unknown event names pass through rather than raising, so new event types will not break your consumer.

```python
from youdotcom import You
from youdotcom.research_helpers import research_background, stream_research

with You() as you:
    handle = research_background(you, input="Summarize the 2025 EU AI Act implementation timeline")

    for event in stream_research(you, handle.task_id):
        print(f"[{event.id}] {event.event}: {event.data}")

    # The stream closes at a terminal status; fetch the full result afterwards
    task = you.get_research_task(task_id=handle.task_id)
    print(task.result.output["content"])
```

[View full API reference](/docs/api-reference/research/v1-research)

## Next Steps

#### [Research API Overview](/docs/guides/research)

Effort levels, including `frontier`, and pricing

#### [Structured Output](/docs/guides/research/structured-output)

Return JSON that follows a schema on a background task

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

Task status endpoint