APIsResearch APIFeatures

Background Requests

Queue long-running research and poll or stream for the result.

View as MarkdownOpen in Claude

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.

FieldTypeDefaultDescription
backgroundbooleanfalseWhen 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:

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

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():

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.

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

Next Steps

Research API Overview

Effort levels, including frontier, and pricing

Structured Output

Return JSON that follows a schema on a background task

API reference

Task status endpoint