How can longer OpenAI web research runs return more source content?

Definition: return_token_budget is a setting on OpenAI's Responses API web_search tool. On supported GPT-5+ reasoning web search runs, unlimited removes the standard returned-token budget for web search result content.

Key facts

• OpenAI recommends { "type": "web_search" } for new Responses API integrations. Its legacy web_search_preview tool does not support return_token_budget.
• default uses the standard returned-token budget and has the same behavior as omitting the setting. unlimited removes that default budget.
• The setting applies to the hosted Responses API web_search tool with GPT-5+ reasoning web search. It excludes non-reasoning web search, Chat Completions search models, container web search and web_search_preview.
• Only default and unlimited are supported values. OpenAI documents null, numbers and other strings as rejected inputs.
• search_context_size is a separate control with low, medium and high values. It does not set an exact token count or a specific number of sources or citations.
• OpenAI says unlimited can increase latency and cost. For multi-search tasks that run for a long time, the guide recommends background: true.

What does return_token_budget change?

The setting changes how much web search result content the tool can return during one Responses API search run. The standard default value leaves the ordinary returned-token budget in place. unlimited removes that budget for a supported reasoning search, which is intended for high-effort research or evaluation runs that may inspect many pages.

The setting concerns content returned by the web search tool. OpenAI documents search_context_size separately as guidance for how much context from search results is made available before the model generates its response. The guide says that this context setting does not set an exact token count or a specific number of sources or citations. OpenAI's web search documentation also describes inline URL citations in the resulting message.

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "xhigh" },
  tools: [
    {
      type: "web_search",
      return_token_budget: "unlimited",
    },
  ],
  input: "Research the economic impact of semaglutide on global healthcare systems.",
});

Which searches support the setting?

The documented scope is narrow: use the hosted web_search tool in the Responses API with GPT-5+ reasoning web search. The guide lists web_search_preview as a legacy integration and says it lacks newer controls, including return_token_budget. Its limitations section also says Chat Completions search models lack the Responses API's returned-token budget control. A request using a non-reasoning search path therefore has no documented support for this setting.

The tool remains optional when tool_choice is auto, because the model can decide whether to search based on the prompt. That choice is separate from the returned-token budget. Supplying return_token_budget changes the budget available during a search run that the model actually starts.

How should a longer run be executed?

OpenAI recommends using unlimited selectively because it can increase latency and cost. The web search guide pairs long-running multi-search work with background mode. Background mode starts the response asynchronously, and the client can poll response objects for status.

The background-mode documentation says to set background to true, then poll the response while its status is queued or in_progress. When the response leaves those states, it has reached a terminal state. A request can therefore combine the web search tool setting with asynchronous response handling:

{
  "model": "gpt-6-astra",
  "reasoning": {"effort": "xhigh"},
  "background": true,
  "tools": [{
    "type": "web_search",
    "return_token_budget": "unlimited"
  }]
}

Related terms

• Agentic search
• ChatGPT deep research
• ChatGPT search

FAQ

Does unlimited enlarge the search context window?

No. OpenAI documents return_token_budget as the returned-token budget for web search results. The web search context window is limited to 128k even when the model context window is larger.

Can I provide a numeric token limit?

No. The documented values are default and unlimited; null, numbers and other strings are rejected.

Does the setting work with web_search_preview?

No. The legacy preview tool lacks this control. The documented path is the hosted Responses API web_search tool with GPT-5+ reasoning web search.

Sources

1. OpenAI, "Web search", Accessed 17 October 2026
2. OpenAI, "Background mode", Accessed 17 October 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer