How many files can you upload to an OpenAI Assistant?

You can attach a maximum of 20 files directly to an OpenAI Assistant instance or conversation thread for tools like Code Interpreter. For the File Search tool, you can attach thousands of files per vector store, and assistants can connect to multiple vector stores to access larger document collections.

What is the file size limit for OpenAI Assistants API?

The maximum file size supported by the OpenAI Assistants API is 512 MB per file for both File Search and Code Interpreter. Additionally, each file uploaded for File Search must not exceed 5,000,000 tokens of extracted text, regardless of file size.

How do you attach more than 20 files to an OpenAI Assistant?

To use more than 20 files with an OpenAI Assistant, add your documents to a vector store and enable the File Search tool, which supports up to 10,000 files per store. Alternatively, connect your assistant to an external intelligent workspace like Fast.io via the Model Context Protocol to query indexed documents without direct file uploads.

How much does vector store storage cost in OpenAI Assistants?

OpenAI provides 1 GB of vector store storage for free across your organization. Beyond the first gigabyte, vector store storage costs $0.10 per GB per day, calculated on the size of parsed text chunks and embedding vectors rather than raw file disk size.

What happens if a file exceeds 5,000,000 tokens in File Search?

If an uploaded file contains more than 5,000,000 tokens of extractable text, OpenAI rejects the document during the vector store ingestion and chunking process. To resolve this error, split large text documents or data dumps into smaller logical files before uploading.

Can an OpenAI Assistant access external files without uploading them?

Yes. An OpenAI Assistant can access external documents through function calling or the Model Context Protocol (MCP). By connecting the assistant to an external service like Fast.io, the model searches indexed files and receives relevant citations without uploading files to OpenAI servers.

OpenAI Assistant File Limits: Upload Caps and Solutions

What Are OpenAI Assistant File Limits and Upload Caps?

According to official OpenAI platform documentation, the maximum file size is 512 MB and each file should contain no more than 5,000,000 tokens per file. Understanding the openai assistant file limit requires distinguishing between three separate boundaries: direct attachments to an assistant instance, vector store capacity for semantic retrieval, and the model context window.

Many developers encounter upload errors because they treat the Assistants API as a general-purpose file hosting service. OpenAI designed its file ingestion pipeline around two specific tools: Code Interpreter and File Search. Each tool enforces distinct constraints on file counts, file sizes, and parsing depth. When an application uploads a file, the platform validates file format, measures disk volume, and parses textual content to calculate token density.

The quotable definition helps frame these constraints clearly: "The OpenAI Assistant file limit encompasses the 20-file direct attachment limit per assistant, the 512 MB per-file size cap, and the 5,000,000 token per-file ceiling enforced by the OpenAI Assistants API, defining how developers attach more than 20 files."

To navigate these constraints, developers must evaluate how their documents flow through the API. The following table details the hard technical limits enforced across OpenAI tools and interfaces.

Limit Category	Constraint Value	Context or Tool	Technical Enforcement
Direct Assistant Attachments	20 files	Code Interpreter	Hard limit per assistant or message thread
Custom GPT Knowledge Base	20 files	ChatGPT Web Interface	Upload cap in user interface configuration
Vector Store File Capacity	10,000 files	File Search tool	Maximum indexed documents per vector store
Maximum File Size	512 MB	File Search and Code Interpreter	Hard cap per uploaded file
Maximum Token Count	5,000,000 tokens	File Search indexing	Extracted text ceiling per individual file
Default Chunk Size	800 tokens	Vector store parser	Configurable between 100 and 4,096 tokens
Default Chunk Overlap	400 tokens	Vector store parser	Up to half of the configured chunk size
Organization Storage Quota	100 GB	Account storage pool	Account default across all uploaded files
Vector Store Storage Cost	$0.10/GB/day	Parsed chunks and embeddings	Billed daily after the first 1 GB free allocation

When working with the openai assistants api file limit, exceeding any of these thresholds halts processing. Uploading a file that breaches the platform size threshold triggers an immediate HTTP 400 validation error during the initial Files API request. Similarly, attempting to attach a 21st file directly to Code Interpreter returns an invalid request error.

The 20-File Direct Attachment Boundary

The 20-file direct upload ceiling applies specifically to files mounted directly into tool configurations or attached to individual conversation threads. When using Code Interpreter, the execution sandbox mounts files into the local environment. Because the sandbox maintains memory and disk state for Python execution, OpenAI caps active attachments to 20 files per assistant instance.

This constraint also surfaces in the ChatGPT user interface for Custom GPTs. In the GPT builder, the Knowledge section accepts a maximum of 20 files. Development teams often confuse this interface restriction with the underlying capacity of the Assistants API, assuming the entire platform caps knowledge bases at 20 files. In reality, the 20-file ceiling applies to direct file attachments, whereas vector stores handle much larger collections.

Organization Storage Quotas

Beyond per-file and per-tool limits, OpenAI enforces a default organization-wide storage quota of 100 GB across all uploaded files. This quota tracks every file created with the Files API, including files uploaded for fine-tuning, assistants, code interpretation, and vision tasks.

Once an organization reaches the default storage threshold, subsequent uploads fail until developers delete older assets or request a quota increase through OpenAI developer support. In automated deployment pipelines where test suites upload test documents repeatedly, orphan files accumulate quickly, causing unexpected quota exhaustion.

More on this subject: Agent File and Document Workflows (218 guides)

How Direct Attachments Compare to Vector Store Retrieval

Solving openai assistants max files errors requires choosing the right tool for the job. Developers frequently experience friction because they attempt to use direct file attachments for search problems, or vector stores for computational data analysis. Direct attachments provide raw file access to a computational sandbox, while vector stores parse documents into searchable semantic fragments.

Understanding the fundamental boundary between direct execution and semantic retrieval is essential for designing high-performance agent architectures. If an assistant needs to read rows from an active spreadsheet or generate charts, direct attachment to Code Interpreter is necessary. If the assistant needs to answer factual questions from hundreds of policy documents, vector stores provide the proper retrieval mechanism.

Choosing between these mechanisms determines whether your application hits the 20-file ceiling or scales smoothly across thousands of documents.

Code Interpreter Sandboxed Execution

Code Interpreter runs an isolated, containerized Python environment. When you pass files directly to an assistant configured with Code Interpreter, the platform uploads those files into the execution environment. The model writes Python scripts to inspect columns, calculate statistics, generate charts, and transform structured files like CSV, JSON, and XLSX.

Because every attached file consumes local disk resources and memory in the ephemeral sandbox, the platform strictly enforces the 20-file limit per assistant. If your application needs to analyze 50 individual CSV files simultaneously, Code Interpreter cannot accept them as separate attachments. You must either concatenate the data into a single consolidated file within platform size limits or process files iteratively across separate runs.

Vector Stores and Semantic Chunking

The File Search tool bypasses the 20-file sandbox limit by using vector stores. Instead of mounting raw files into a runtime environment, vector stores ingest documents through an automated extraction, chunking, and embedding pipeline.

When you add files to a vector store, OpenAI extracts the raw text and splits it into discrete passages. By default, the chunk size is 800 tokens with a 400-token overlap between consecutive chunks. You can customize the chunking strategy, setting chunk sizes between 100 and 4,096 tokens. The platform generates embeddings for each chunk and stores them in a managed vector database.

A single vector store accommodates extensive document collections, supporting thousands of indexed files. During assistant runs, the model issues search queries against the vector store, retrieves the most relevant chunks, and injects those excerpts into the context window. This architecture enables retrieval-augmented generation across substantial technical libraries without attaching raw files to the model.

Supported Document Formats and Encodings

The File Search tool supports common document and text formats, including PDF, DOCX, TXT, Markdown, HTML, JSON, and common programming source code files such as Python, JavaScript, TypeScript, C++, and Go. For text MIME types, OpenAI requires UTF-8, UTF-16, or ASCII character encoding.

Documents that contain unextractable text cause indexing failures. Scanned PDF documents without embedded text layers fail ingestion unless processed with optical character recognition prior to upload. Similarly, password-protected PDFs, malformed XML files, and proprietary binary archives return processing errors during vector store batch ingestion.

Why Vector Store Storage Economics Matter at Scale

While vector stores solve the 20-file attachment bottleneck, they introduce ongoing operational costs and token processing ceilings. Teams building production systems must account for how OpenAI meters vector store storage and calculates document density. High-volume document indexing can quickly transform an experimental assistant into an expensive ongoing infrastructure commitment.

OpenAI charges for vector store storage beyond 1 GB at a rate of $0.10 per GB per day based on parsed chunks and embeddings. This pricing model differs significantly from commodity object storage, where storage is billed monthly rather than daily.

Understanding the financial and technical mechanics of vector stores helps prevent unexpected invoices and failed ingestion jobs as your agent workflows expand.

Calculating Daily Vector Store Storage Costs

Vector store billing does not track the raw byte size of your original uploaded file. Instead, OpenAI meters storage based on the size of parsed text chunks and their corresponding embedding vectors. The initial 1 GB of vector store storage across your organization is free. Beyond that baseline, storage costs accrue daily.

The following table illustrates how daily vector store rates scale into cumulative monthly expenditures across typical knowledge base volumes.

Indexed Storage Volume	Daily Ingestion Rate	Projected Monthly Expenditure
10 GB of indexed files	$0.90 per day	$27.00 per month
50 GB of indexed files	$4.90 per day	$147.00 per month
100 GB of indexed files	$9.90 per day	$297.00 per month
500 GB of indexed files	$49.90 per day	$1,497.00 per month

In high-volume applications where multiple assistants maintain dedicated vector stores with duplicate documents, storage costs accumulate rapidly. Unlike standard database storage where data is queried on demand, vector store fees accrue continuously every day the store exists, regardless of query activity.

The Token Ceiling Versus File Size

Developers often focus exclusively on raw byte thresholds, overlooking the companion token ceiling enforced during indexing. OpenAI evaluates both constraints independently. Exceeding either limit results in ingestion failure.

The relationship between file size and token count depends entirely on document formatting and data density. The table below compares how different document formats interact with platform ingestion limits.

Document Format Profile	Physical File Size	Extracted Token Count	Ingestion Pipeline Outcome
Graphical PDF / Technical Presentation	450 MB	110,000 tokens	Accepted (within size and token limits)
Dense Text Export / Raw JSON Log Dump	35 MB	6,200,000 tokens	Rejected (exceeds token ceiling)

As illustrated in the comparison above, token density dictates whether a file can be indexed. A document with substantial graphical media easily fits within both limits, whereas dense plain text logs breach the token ceiling long before reaching the file size boundary. When preparing technical corpora for assistant retrieval, calculating token density before initiating uploads prevents rejection.

Automating Expiration and Lifecycle Policies

To mitigate runaway storage fees, the Assistants API supports vector store expiration policies through the expires_after parameter. This configuration allows you to set an anchor (such as last_active_at) and a duration in days.

If a vector store receives no search queries or file updates within the configured duration, OpenAI automatically deletes the vector store and its associated embeddings. For temporary customer support threads, automated onboarding sessions, or transient research agents, configuring a 7-day or 14-day expiration policy prevents stale indices from inflating monthly cloud expenditures.

Store and Search Agent Files Without Upload Caps

Connect your AI assistants to Fast.io persistent workspaces via MCP. Index large corpora automatically with semantic search and version control. Every organization starts with a 14-day free trial.

Start 14-Day Trial

How to Scale Past Native File Limits with External Storage

When building enterprise AI applications, teams routinely encounter corpora that exceed native upload caps, token boundaries, and budget tolerances. Handling hundreds of gigabytes of documentation, thousands of user-specific folders, or cross-model workflows requires moving beyond direct assistant uploads. Relying solely on hosted vector databases can restrict data portability and inflate recurring platform expenses.

Engineering teams implement three primary architectural patterns to overcome OpenAI assistant file limits: multi-store partitioning, dynamic vector rotation, and external intelligent workspace storage. Each approach presents distinct operational tradeoffs between architectural complexity, query latency, and ongoing maintenance overhead.

Comparing these approaches allows you to preserve retrieval precision while maintaining control over infrastructure costs and data governance across multi-agent environments.

Smart summaries and automated workspace indexing

Multi-Store Partitioning and Routing

When a knowledge base exceeds the capacity of a single store, developers partition files across multiple distinct vector stores. Instead of creating a monolithic knowledge repository, you organize stores by department, product line, or temporal cohort.

During query processing, an intent classification step inspects the user query and routes the request to the appropriate vector store ID. This pattern keeps individual vector stores within manageable thresholds and improves retrieval relevance by narrowing the search space. However, multi-store partitioning requires custom routing middleware and does not reduce ongoing per-gigabyte daily storage charges.

Connecting External Workspaces via Model Context Protocol

A more flexible architecture decouples document storage from model vendors entirely. Instead of uploading proprietary files to OpenAI vector stores, teams store documents in an intelligent workspace on Fast.io.

Fast.io provides persistent cloud workspaces for agentic teams. When documents are placed in a Fast.io workspace, Intelligence Mode automatically indexes the files for semantic retrieval, full-text search, and metadata querying. Rather than attaching raw files to an OpenAI assistant, the assistant connects to Fast.io using the remote Model Context Protocol (MCP) server.

The Fast.io MCP server is available over Streamable HTTP at https://mcp.fast.io/mcp and legacy SSE at https://mcp.fast.io/sse. When an assistant requires document context, it calls the MCP search tool, retrieves verified citations, and incorporates relevant excerpts into its response. This approach leaves OpenAI's 20-file direct upload cap untouched while providing access to thousands of documents.

External workspace storage also eliminates vendor lock-in. The same Fast.io workspace and search index can serve OpenAI assistants, Claude agents, local LLMs, and human team members simultaneously.

Importing Existing Cloud Corpora

Migrating existing file libraries into an agent workflow often involves complex data staging. Fast.io simplifies document ingestion through cloud import capabilities. Teams can import files directly from Google Drive, Dropbox, Box, and OneDrive, or pull assets via URL without routing data through local developer machines.

Once imported, files inherit workspace permissions, automated version tracking, and instant search indexing. Agents can query the corpus immediately, bypassing repetitive file uploads across different AI platforms.

Best Steps for Managing Production Agent Knowledge Bases

Operating AI assistants in production requires rigorous data hygiene, structured extraction pipelines, and auditable governance. Implementing disciplined file management patterns ensures high retrieval quality and protects sensitive operational data across autonomous systems. As teams expand their automated document operations, unstructured file dumps inevitably create retrieval noise and compliance vulnerabilities.

When scaling agent deployments, organizations must look beyond raw file storage and establish structured workflows for document ingestion, version control, and human oversight. Establishing clear operational boundaries prevents data duplication, reduces token consumption, and keeps production knowledge bases accurate over time.

The following practices help development teams maintain reliable document pipelines while scaling agent deployments across organizations.

Document Normalization and Structured Extraction

Raw documents rarely arrive in optimal formats for retrieval-augmented generation. Word documents contain bloated styling metadata, PDFs include complex multi-column layouts, and spreadsheets mix numerical tables with explanatory notes.

Before indexing documents, implement a normalization pipeline that strips decorative markup, preserves structural Markdown headings, and extracts tabular data into clean JSON schemas. Normalization reduces token consumption and eliminates unreadable character artifacts that degrade retrieval precision.

When applications require structured data extraction from invoices, contracts, or forms, rely on Metadata Views. Metadata Views turn unstructured documents into live, queryable databases. Users define extraction fields in natural language, and the platform generates a typed schema across text, integer, decimal, boolean, date, and JSON types. AI agents can create views, trigger extractions, and query structured records via MCP without managing brittle regex rules or manual OCR templates.

Version History and Immutability

In multi-agent environments where agents write reports, edit code, and update shared summaries, concurrent file access can lead to accidental overwrites. OpenAI's Files API provides no native file versioning; updating a file requires uploading a replacement file and obtaining a new file ID.

Using persistent workspaces on Fast.io Workspaces provides built-in, per-file version history. Every modification creates an auditable revision. If an autonomous agent generates an erroneous edit or overwrites a critical reference document, team members can inspect previous versions and restore earlier states instantly.

Complementing version history, the append-only audit log records every file read, write, share creation, and permission change. This transparency provides complete visibility into what files an agent accessed, when operations occurred, and which human or machine identity initiated the action.

Agent-to-Human Ownership Transfer

A common production deployment pattern involves autonomous setup agents configuring workspaces for client engagements or internal departments. In this workflow, an agent creates the organization workspace, organizes document hierarchies, ingests project files, and establishes branded shares.

Fast.io supports clean ownership transfer. Once the initial workspace configuration and document indexing are complete, the agent transfers primary workspace ownership to a human team member or client administrator. The agent retains administrative or scoped tool access to update files, while human stakeholders maintain full commercial and governance control over the shared environment.

When onboarding, creating a user account is free, while running active organizations requires a paid subscription. Every organization starts with a 14-day free trial, which requires a credit card. Plans are Starter at $9.99/mo, Business at $49.99/mo, and Enterprise at $199.99/mo, giving teams scalable capacity for production agent workloads.

OpenAI Assistant File Limits: Upload Caps, Size Limits, and Solutions