> For the complete documentation index, see [/llms.txt](/llms.txt).

> Source: /docs/capabilities/search/file-search

# File Search

> File Search is currently in **Beta**. Features and API specifications may change without prior notice.
> During the beta period, please avoid uploading sensitive or confidential data.
> When the service officially launches, data from users who have not agreed to the terms of service may be deleted.

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](https://console.upstage.ai))
- A file uploaded via the [Files API](/docs/agents/files) — you'll need the returned `file_id` to add it to a vector store

### Create a Vector Store

#### curl

```bash
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"
  }'
```

#### Python

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UPSTAGE_API_KEY"],
    base_url="https://api.upstage.ai/v2",
)

# Create a vector store
vector_store = client.vector_stores.create(name="my-knowledge-base")
print(vector_store.id)  # e.g., "vs_abc123..."
```

Response:

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

### Add a File

To add a file to a vector store, you need a `file_id` from the [Upstage Files API](/docs/agents/files). First upload your file, then add it to the vector store.

#### curl

```bash
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"
  }'
```

#### Python

```python
file_obj = client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id="file_xyz789",
)
print(file_obj.status)  # "in_progress"
```

Response:

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

### Wait for Indexing

File indexing is asynchronous. Poll the file status until it becomes `completed`.

#### curl

```bash
# 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'])"
```

#### Python

```python
import time

while True:
    f = client.vector_stores.files.retrieve(
        vector_store_id=vector_store.id,
        file_id=file_obj.id,
    )
    if f.status == "completed":
        print("File indexed successfully!")
        break
    elif f.status == "failed":
        print("Indexing failed:", f.last_error)
        break
    time.sleep(2)
```

### Search

#### curl

```bash
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
  }'
```

#### Python

```python
results = client.vector_stores.search(
    vector_store_id=vector_store.id,
    query="What is the main topic of the document?",
    max_num_results=5,
)
for item in results.data:
    text = "".join(block.text for block in item.content if block.type == "text")
    print(f"[{item.score:.3f}] {item.filename}: {text[:100]}...")
```

### Get an AI-Generated Answer (RAG)

#### curl

```bash
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"]
      }
    ]
  }'
```

#### Python

```python
result = client.responses.create(
    model="solar-pro4",
    input="Summarize the key points of my document.",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": [vector_store.id],
        }
    ],
)
print(result.output)
```

---

## Supported File Types

| Extension       | Format                |
| --------------- | --------------------- |
| `.pdf`          | PDF documents         |
| `.docx`         | Microsoft Word        |
| `.pptx`         | Microsoft PowerPoint  |
| `.xlsx`         | Microsoft Excel       |
| `.hwp`, `.hwpx` | Hangul Word Processor |
| `.md`           | Markdown              |
| `.txt`          | Plain text            |
| `.jpeg`, `.jpg` | JPEG images           |
| `.png`          | PNG images            |
| `.bmp`          | BMP images            |
| `.tiff`, `.tif` | TIFF images           |
| `.heic`         | HEIC images           |

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

---

## Error Handling

All errors follow a consistent format:

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

### Common Errors

| HTTP Status | Type                    | Cause                                                                                                     |
| ----------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
| 400         | `invalid_request_error` | Unsupported file type, missing required fields, or service limit exceeded (`code: "max_limit_exceeded"`). |
| 401         | —                       | Missing or invalid API key in the `Authorization` header.                                                 |
| 404         | —                       | Vector store or file not found.                                                                           |
| 422         | `invalid_request_error` | Invalid `chunking_strategy` (only `auto` is supported), invalid metadata or attributes (exceeds limits).  |

---

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

```bash
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"]
  }'
```

### Python

```python
batch = client.vector_stores.file_batches.create(
    vector_store_id=vector_store.id,
    file_ids=["file_001", "file_002", "file_003"],
)
print(batch.status)  # "in_progress"
```

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

```python
# 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:

```python
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`:

```python
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

| Resource               | Limit |
| ---------------------- | ----- |
| Vector stores per user | 50    |
| Files per vector store | 500   |
| Files per batch        | 50    |

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

### Data Constraints

| Constraint                    | Value                    |
| ----------------------------- | ------------------------ |
| Metadata keys per object      | 16                       |
| Metadata key length           | 64 characters            |
| Metadata value length         | 512 characters           |
| Attributes keys per file      | 16                       |
| Attribute key length          | 64 characters            |
| Attribute string value length | 512 characters           |
| `max_num_results` range       | 1-20 (default: 5)        |
| `expires_after.days` range    | 1-365                    |
| Pagination `limit` range      | 1-100 (default: 20)      |
| Chunking strategy             | Only `auto` is supported |