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

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

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

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