File Search

File Search enables you to search across your documents using natural language queries. Upload files, build a vector store, and retrieve relevant information — or get AI-generated answers grounded in your documents using the Responses API.

Concepts

Vector Stores

A vector store is a container that holds your indexed documents. When you upload a file to a vector store, the system automatically parses, chunks, and embeds the content so it can be searched.

Each vector store is isolated — files in one vector store are not searchable from another. Vector stores are scoped per user (identified by API key). You can only access vector stores that you created, and other users cannot see or search your data.

File Indexing

When you add a file to a vector store, the system processes it through an asynchronous pipeline:

1. Parse — Extract text content from the file (supports images, PDFs, Microsoft Office documents, and more).
2. Chunk — Split the extracted text into optimized segments.
3. Embed — Generate vector embeddings for each chunk.
4. Store — Save the embeddings for search.

File processing is asynchronous. After adding a file, its status starts as in_progress and transitions to completed when indexing finishes, or failed if an error occurs.

Search

Search takes a natural language query, embeds it, and finds the most relevant document chunks in the vector store. Results include the matched text, relevance score, and source file information.

Responses (RAG)

The Responses API combines search with an LLM. It retrieves relevant document chunks, then generates an AI answer grounded in the retrieved context. This is also known as Retrieval-Augmented Generation (RAG).

Quick Start

This guide walks you through creating a vector store, uploading a file, and performing your first search.

Prerequisites

• An Upstage API key (obtain from Upstage Console)
• A file uploaded via the Files API — you'll need the returned file_id to add it to a vector store

curl -X POST https://api.upstage.ai/v2/vector_stores \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-knowledge-base"
  }'

{
  "id": "vs_abc123def456",
  "object": "vector_store",
  "created_at": 1711644800,
  "name": "my-knowledge-base",
  "usage_bytes": 0,
  "file_counts": {
    "in_progress": 0,
    "completed": 0,
    "failed": 0,
    "cancelled": 0,
    "total": 0
  },
  "status": "completed",
  "last_active_at": 1711644800,
  "expires_after": null,
  "expires_at": null,
  "metadata": {}
}

curl -X POST https://api.upstage.ai/v2/vector_stores/vs_abc123def456/files \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file_xyz789"
  }'

{
  "id": "file_xyz789",
  "object": "vector_store.file",
  "created_at": 1711644900,
  "vector_store_id": "vs_abc123def456",
  "status": "in_progress",
  "last_error": null,
  "usage_bytes": 0,
  "chunking_strategy": {"type": "auto"},
  "attributes": null
}

# Poll until status is "completed" or "failed"
curl -s https://api.upstage.ai/v2/vector_stores/vs_abc123def456/files/file_xyz789 \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])"

curl -X POST https://api.upstage.ai/v2/vector_stores/vs_abc123def456/search \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the main topic of the document?",
    "max_num_results": 5
  }'

curl -X POST https://api.upstage.ai/v2/responses \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "solar-pro4",
    "input": "Summarize the key points of my document.",
    "tools": [
      {
        "type": "file_search",
        "vector_store_ids": ["vs_abc123def456"]
      }
    ]
  }'

Supported File Types

All file types are processed using document parsing to extract text content before indexing.

Error Handling

All errors follow a consistent format:

{
  "error": {
    "message": "Description of the error.",
    "type": "error_type",
    "code": null
  }
}

Common Errors

File Batches

File batches allow you to add multiple files to a vector store in a single request. This is useful when you need to index many files at once.

curl -X POST https://api.upstage.ai/v2/vector_stores/vs_abc123def456/file_batches \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_ids": ["file_001", "file_002", "file_003"]
  }'

You can check the batch status and list the files in a batch:

# Check batch status
batch = client.vector_stores.file_batches.retrieve(
    vector_store_id=vector_store.id,
    batch_id=batch.id,
)
print(batch.file_counts)

# List files in a batch
files = client.vector_stores.file_batches.list_files(
    vector_store_id=vector_store.id,
    batch_id=batch.id,
)
for f in files:
    print(f.id, f.status)

To cancel an in-progress batch:

batch = client.vector_stores.file_batches.cancel(
    vector_store_id=vector_store.id,
    batch_id=batch.id,
)

Batch Status and Completion

A batch's status field reflects whether the batch was cancelled, not whether indexing finished. It can be either of:

• in_progress — set on creation. Remains in_progress even after every file in the batch reaches a terminal state.
• cancelled — set when POST .../cancel is called on an in_progress batch. Already-cancelled batches return as-is (no-op).

To detect when batch indexing is done, poll file_counts rather than status. A batch is functionally complete when file_counts.in_progress reaches 0:

import time

while True:
    batch = client.vector_stores.file_batches.retrieve(
        vector_store_id=vector_store.id,
        batch_id=batch.id,
    )
    counts = batch.file_counts
    if counts.in_progress == 0:
        break
    time.sleep(2)

# Inspect terminal counts
if counts.failed > 0:
    # Some files failed indexing — list files with filter=failed to inspect last_error
    failed_files = client.vector_stores.file_batches.list_files(
        vector_store_id=vector_store.id,
        batch_id=batch.id,
        filter="failed",
    )

Per-file failures do not change the batch status. They are aggregated into file_counts.failed.

Limitations and Constraints

Service Limits

These limits are enforced at creation time. Exceeding a limit returns a 400 error with code: "max_limit_exceeded".

Data Constraints