OpenAI Web Search

Search the web using OpenAI models with the web_search_preview tool.

Overview

OpenAI Web Search uses the Responses API (POST /responses) with the web_search_preview tool to perform grounded web searches. The model searches the web for relevant information and returns a synthesized answer with source annotations. Supports configurable search context size (low/medium/high), model selection, system prompts, temperature, and max output tokens. Returns the response text along with an array of source URLs and annotations extracted from the search results.

Category: AI
Tool Name: openai_web_search
Version: 1

Appearance: Icon: openai | Color: #10a37f

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires OpenAI credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Model	options	No	(current default)	The OpenAI model to use for web search. Always uses the latest version (auto-updated).
				Options: the OpenAI chat models available to your workspace — pick one from the dropdown.
System Prompt	string	No	—	System instructions that set the behavior and persona of the model. Leave empty for default behavior. Supports expressions.
User Message	string	Yes	—	The search query or prompt to send. If empty, falls back to item.json.message or item.json.prompt. Supports expressions.
Search Context Size	options	No	medium	How much web search context to provide to the model.
				Options: low (minimal context — faster, fewer sources), medium (balanced), high (maximum context — more sources, more detail, slower)
Options	collection	No	{}	Optional generation settings — add only the fields you need.
— Temperature	number	No	1	Sampling temperature (0-2). Lower values make output more focused and deterministic.
— Max Output Tokens	number	No	4096	Maximum number of tokens the model can generate in the response.
— Response Field Name	string	No	response	Field name in the output JSON where the response text will be placed.
Include Input	boolean	No	false	Whether to include the original input item fields in the output alongside the response.
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

One output item per input item. The synthesized answer lands on the field named by Response Field Name (response by default), with the citations in sources, plus model and usage. The rest of the input item JSON is dropped unless Include Input is on; binary data on the input item is forwarded unchanged.

{
  "response": "The synthesized, web-grounded answer",
  "sources": [
    { "url": "https://example.com/article", "title": "Article title", "startIndex": 42, "endIndex": 98 }
  ],
  "model": "the model that produced the answer",
  "usage": { "input_tokens": 900, "output_tokens": 350 }
}

• sources contains one entry per URL citation the model attached to its answer. startIndex and endIndex mark the character range of the answer text that the citation supports.
• sources is an empty array when the model answered without citing anything — check its length before assuming an answer is grounded.

Reference the result downstream by expression, e.g. {{ $json.response }} or {{ $json.sources[0].url }}.

Usage Examples

• Search the web for the latest news on a topic
• Research a question using OpenAI web search with source citations
• Find current information about a company or product
• Get up-to-date facts with web-grounded answers
• Lookup recent events and return sources

Example Configuration

Fast fact lookup:

{
  "type": "openai_web_search",
  "parameters": {
    "userMessage": "{{ $json.question }}",
    "searchContextSize": "low"
  }
}

Thorough research with citations required:

{
  "type": "openai_web_search",
  "parameters": {
    "systemPrompt": "Answer only from the sources you find, and cite each claim.",
    "userMessage": "What changed in {{ $json.topic }} in the last month?",
    "searchContextSize": "high",
    "options": {
      "temperature": 0.2,
      "maxOutputTokens": 2048,
      "responseFieldName": "research"
    }
  }
}

Enrich each incoming record without losing its fields:

{
  "type": "openai_web_search",
  "parameters": {
    "userMessage": "Give a two-sentence company profile for {{ $json.companyName }}.",
    "includeInput": true,
    "maxConcurrency": 5,
    "options": {
      "responseFieldName": "companyProfile"
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

OpenAI Web Search queries the live web using OpenAI models via the Responses API with the web_search_preview tool, delivering synthesized answers grounded in current sources. Use it when a workflow needs real-time information beyond a model training cutoff, such as recent news, current pricing, or live data lookups. It produces a response text field containing the synthesized answer alongside an array of source URLs and inline annotations extracted from the search results.