YOyou

Returns comprehensive research-grade answers with multi-step reasoning

Changed on

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.

post/v1/research

Request

Request body

inputstring 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.
output_schemaobject

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 for full rules, supported patterns, the optional-via-nullable pattern, conditional structure, and examples.

backgroundboolean

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

Example request

{
  "input": "Which global cities improved air quality the most over the past 10 years, and what measurable actions contributed?",
  "research_effort": "lite",
  "source_control": {
    "include_domains": [
      "nytimes.com",
      "bbc.com"
    ],
    "exclude_domains": [
      "spam-site.com",
      "other-site.com"
    ],
    "boost_domains": [
      "nytimes.com",
      "wired.com"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "gtin": {
        "type": [
          "string",
          "null"
        ]
      }
    },
    "required": [
      "name",
      "gtin"
    ],
    "additionalProperties": false
  }
}

Response

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.

OR

Example response

{
  "output": {
    "content_type": "text",
    "sources": [
      {
        "url": "https://sustainablemobility.iclei.org/air-pollution-beijing/",
        "title": "Clearing the skies: how Beijing tackled air pollution & what lies ahead",
        "snippets": [
          "The city actively coordinated air pollution control measures with surrounding areas, such as the Beijing-Tianjin-Hebei region."
        ]
      }
    ]
  },
  "warnings": []
}

Changes

  • 24d9e2eb5297Revision changes
    • breaking

      request property / was restricted to a list of enum values

    • breaking

      the / request property type changed from string to no type

    • breaking

      added to the response body oneOf list for the response status

    • info

      added the new AR enum value to the request property /

    • info

      added the new AT enum value to the request property /

    • info

      added the new AU enum value to the request property /

    • info

      added the new BE enum value to the request property /

    • info

      added the new BR enum value to the request property /

    • info

      added the new CA enum value to the request property /

    • info

      added the new CH enum value to the request property /

    • info

      added the new CL enum value to the request property /

    • info

      added the new CN enum value to the request property /

    • info

      added the new DE enum value to the request property /

    • info

      added the new DK enum value to the request property /

    • info

      added the new ES enum value to the request property /

    • info

      added the new FI enum value to the request property /

    • info

      added the new FR enum value to the request property /

    • info

      added the new GB enum value to the request property /

    • info

      added the new HK enum value to the request property /

    • info

      added the new ID enum value to the request property /

    • info

      added the new IN enum value to the request property /

    • info

      added the new IT enum value to the request property /

    • info

      added the new JP enum value to the request property /

    • info

      added the new KR enum value to the request property /

    • info

      added the new MX enum value to the request property /

    • info

      added the new MY enum value to the request property /

    • info

      added the new NL enum value to the request property /

    • info

      added the new NO enum value to the request property /

    • info

      added the new NZ enum value to the request property /

    • info

      added the new PH enum value to the request property /

    • info

      added the new PL enum value to the request property /

    • info

      added the new PT enum value to the request property /

    • info

      added the new RU enum value to the request property /

    • info

      added the new SA enum value to the request property /

    • info

      added the new SE enum value to the request property /

    • info

      added the new TR enum value to the request property /

    • info

      added the new TW enum value to the request property /

    • info

      added the new US enum value to the request property /

    • info

      added the new ZA enum value to the request property /

    • info

      added the new frontier enum value to the request property

    • info

      added subschema #2 to the / request property oneOf list

    • info

      removed from the response body oneOf list for the response status

  • dfadf8aeab9bRevision changes
    • breaking

      added to the response body oneOf list for the response status

    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property