---
title: "Returns comprehensive research-grade answers with multi-step reasoning"
method: POST
path: "/v1/research"
---

# Returns comprehensive research-grade answers with multi-step reasoning

`POST /v1/research`

Research goes beyond a single web search. In response to your question, it runs multiple searches, reads through the sources, and synthesizes everything into a thorough, well-cited answer. Use it when a question is too complex for a simple lookup, and when you need a response you can actually trust and verify.

## Request body

- object
  - `input` string, required — The research question or complex query requiring in-depth investigation and multi-step reasoning. Note: The maximum length of the input is 40,000 characters.
  - `research_effort` 'lite' | 'standard' | 'deep' | 'exhaustive' | 'frontier' — Controls how much time and effort the Research API spends on your question. Higher effort levels run more searches and dig deeper into sources, at the cost of a longer response time. Available levels: - `lite`: Returns answers quickly. Good for straightforward questions that just need a fast, reliable answer. - `standard`: The default. Balances speed and depth, a good fit for most questions. - `deep`: Spends more time researching and cross-referencing sources. Use this when accuracy and thoroughness matter more than speed. - `exhaustive`: The most thorough option. Explores the topic as fully as possible, best suited for complex research tasks where you want the highest quality result. - `frontier`: Designed for long-running, deep research tasks that require the maximum compute budget. Latency ranges from 30s to 12000s (p50: 300s). Requires `background: true` — synchronous requests with `research_effort: "frontier"` return `422`.
  - `source_control` object — Beta. Controls which web sources the research agent searches and visits. Use this to allow specific domains, block specific domains, boost specific domains, filter by recency, or focus web results by country. `include_domains` and `exclude_domains` cannot be used together in the same request. Each domain list is capped at 500 entries. `exclude_domains` also blocks the research agent from visiting pages on those domains during browsing. `boost_domains` gives matching domains a relative ranking boost without filtering out other domains. It can be combined with `exclude_domains` but cannot be combined with `include_domains` (returns `422`).
    - `include_domains` string[] — A list of domains to restrict search results to. Only results from these domains will be returned. Supports up to 500 domains. This is a strict allowlist, not a boost — results are limited exclusively to the specified domains. Cannot be combined with `exclude_domains`; passing both will return a `422` error.
    - `exclude_domains` string[] — A list of domains to exclude from search results. Results from these domains will be filtered out. Supports up to 500 domains. Cannot be combined with `include_domains`; passing both will return a `422` error.
    - `boost_domains` string[] — A list of domains to boost in search ranking. Matching results from these domains receive a fixed relative ranking boost, but this is not a filter. If the boosted domains do not have matching results, results from other domains can still appear. Supports up to 500 domains. Boosted domains are not guaranteed to appear in the final answer — the research agent may still select other sources if they are a better fit for the response. Can be combined with `exclude_domains`. Cannot be combined with `include_domains`. Passing both `boost_domains` and `include_domains` will return a `422` error.
    - `freshness` union — Specifies the freshness of the results to return. Provide either one of `day`, `week`, `month`, `year`, or a date range string in the format `YYYY-MM-DDtoYYYY-MM-DD`. When your search query includes a temporal keyword and you also set a freshness parameter, the search will use the broader (i.e., less restrictive) of the two timeframes. For example, if you use `query=news+this+week&freshness=month`, the results will use a freshness of month.
      - 'day' | 'week' | 'month' | 'year'
      - string
    - `country` 'AR' | 'AU' | 'AT' | 'BE' | 'BR' | 'CA' | 'CL' | 'DK' | 'FI' | 'FR' | 'DE' | 'HK' | 'IN' | 'ID' | 'IT' | 'JP' | 'KR' | 'MY' | 'MX' | 'NL' | 'NZ' | 'NO' | 'CN' | 'PL' | 'PT' | 'PH' | 'RU' | 'SA' | 'ZA' | 'ES' | 'SE' | 'CH' | 'TW' | 'TR' | 'GB' | 'US' — The country code that determines the geographical focus of the web results.
  - `output_schema` object — Beta. Requests structured JSON output in `output.content` using a supported JSON Schema subset. Supported with `research_effort` values `standard`, `deep`, `exhaustive`, and `frontier`. Sending `output_schema` with `research_effort: "lite"` returns `422`. Limits are enforced before model execution. The request fails with `422` if any limit is exceeded: - Max nesting depth: 5. - Max total properties: 100. - Max total enum values: 500. - Max large-enum string budget (enums over 250 values): 7,500. - Max total schema string budget: 25,000. The schema string budget counts property names, `$defs` names, enum values, and `const` values. Schema rules: - Root must be a JSON object. Top-level `anyOf` is not allowed. - Every object must define `properties` and set `additionalProperties: false`. - Every property must be listed in `required`. To make a field optional, keep it in `required` and add `"null"` to its type, for example `["string", "null"]`. - Recursive schemas are not supported. - A property's type may not be a bare `{"type": "null"}`. Use a nullable array form such as `["string", "null"]`, or a `null` branch inside an `anyOf`. See [Structured Output](/docs/guides/research#structured-output) for full rules, supported patterns, the optional-via-nullable pattern, conditional structure, and examples.
  - `background` boolean — When `true`, runs the request asynchronously as a background task. The API returns a task handle immediately instead of waiting for the final answer. Poll `GET /v1/research/{task_id}` or stream progress via `GET /v1/research/{task_id}/stream` to retrieve the result. Useful for `deep` or `exhaustive` research that can exceed client-side timeouts, or when you want to decouple submission from retrieval. Required for `research_effort: "frontier"`.

## Response `200`

In synchronous mode (`background: false`, the default), a JSON object containing a comprehensive answer with citations and supporting search results. In background mode (`background: true`), a JSON object with a task handle that you can poll or stream for the final result.

- union
  - ResearchOutput — The research output containing the answer and sources.
    - `output` object, required — An object containing the content, content type, and source list.
      - `content` union, required — The comprehensive response with inline citations. By default, content is a Markdown string with numbered citations that reference the items in the sources array. When `output_schema` is provided, content is a JSON object that conforms to the requested schema.
        - string
        - object
      - `content_type` 'text' | 'object', required — The format of the content field.
      - `sources` object[], required — A list of web sources used to generate the answer.
        - `url` string, required — The URL of the source webpage.
        - `title` string — The title of the source webpage.
        - `snippets` string[] — Relevant excerpts from the source page that were used in generating the answer.
    - `warnings` string[], required — A list of warnings generated during research, such as source access issues or partial results. Empty when no warnings occurred.
  - ResearchTask — A handle for a background research task returned immediately on submission.
    - `task_id` string, uuid, required — Unique identifier for the background research task.
    - `type` 'research', required — The task type.
    - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required — The status of a background research task.
    - `stream_url` string, required — The URL path for the Server-Sent Events stream for this task.
    - `created_at` string, date-time, required — When the task was created, in RFC 3339 format.

## Other responses

- `401` — Unauthorized. Problems with API key.
- `403` — Forbidden. API key lacks scope for this path.
- `422` — Unprocessable Entity. Request validation failed.
- `500` — Internal Server Error during authentication/authorization middleware.

---

[API](https://skmtc.net/you/apis/you-com-research-api.md) · [All operations](https://skmtc.net/you/apis/you-com-research-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/you/you-com-research-api/versions/24d9e2eb5297/schema)