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

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

# OpenAI File Search

> Search through uploaded files using OpenAI vector stores via the Responses API.

## Overview

OpenAI File Search uses the Responses API (POST /responses) with the file_search tool to search through documents stored in OpenAI vector stores. Provide one or more vector store IDs and a query, and the model will retrieve relevant file content and generate a response with citations. Supports configurable model selection, system prompts, max number of results, temperature, and max output tokens. Returns the response text, file search results with citations, and usage metadata.

**Category:** AI  
**Tool Name:** `openai_file_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 file search and response generation. 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 guide how the model searches and responds. Leave empty for default behavior. Supports expressions. |
| User Message | `string` | Yes | — | The search query or question about the uploaded files. Falls back to item.json.message or item.json.prompt if empty. Supports expressions. |
| Vector Store IDs | `string` | No | — | JSON array of vector store IDs (e.g. '["vs_abc123"]'), or a single vector store ID string. Can also come from item.json.vectorStoreIds. Supports expressions. |
| Options | `collection` | No | `{}` | Optional search and generation settings — add only the fields you need. |
| — Max Results | `number` | No | `5` | Maximum number of file search results to retrieve from the vector store. |
| — 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 answer lands on the field named by **Response Field Name** (`response` by default), with the retrieval record in `fileSearchResults`, 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 answer synthesized from the retrieved documents",
  "fileSearchResults": [],
  "model": "the model that produced the answer",
  "usage": { "input_tokens": 2400, "output_tokens": 310 }
}
```

- `fileSearchResults` holds the file-search calls the model made while answering, exactly as the API reported them. It is an empty array when the model answered without searching.
- Vector stores are created and populated in your OpenAI account — this node reads from them, it does not create them. Use **OpenAI File Upload** to get files into OpenAI first.

Reference the result downstream by expression, e.g. `{{ $json.response }}`.

## Usage Examples

- Search uploaded documents in a vector store for specific information
- Ask questions about PDFs stored in OpenAI and get cited answers
- Retrieve relevant content from a knowledge base using semantic search
- Search multiple vector stores simultaneously for information
- Query legal documents and get responses with file citations

## Example Configuration

Ask a question against one vector store:

```json
{
  "type": "openai_file_search",
  "parameters": {
    "userMessage": "What is the refund window in the policy documents?",
    "vectorStoreIds": "vs_abc123"
  }
}
```

Search several stores, retrieve more passages, and keep the original fields:

```json
{
  "type": "openai_file_search",
  "parameters": {
    "systemPrompt": "Answer only from the retrieved documents and cite the file each fact came from.",
    "userMessage": "{{ $json.question }}",
    "vectorStoreIds": "[\"vs_abc123\", \"vs_def456\"]",
    "includeInput": true,
    "options": {
      "maxNumResults": 20,
      "temperature": 0,
      "responseFieldName": "answer"
    }
  }
}
```

### 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 File Search queries documents stored in OpenAI vector stores by sending a natural language prompt and one or more vector store IDs to the Responses API. Use this tool when workflows need to extract and synthesize information from previously uploaded documents rather than relying on pretrained model knowledge or live web data. It outputs response text with inline citations, ranked file search results linking back to source documents, and usage metadata such as input and output token counts.