<!-- BusyBot node reference — https://busybot.net/tools/openai-web-search/ -->

> Node: OpenAI Web Search (`openai_web_search`) · Action · v1
> Category: AI · Credentials: OpenAI (`openai`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/openai/) 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.

```json
{
  "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:

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

Thorough research with citations required:

```json
{
  "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:

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