---
title: Getting Started with Index V2 | Developer Documentation
description: Create a searchable index over your documents, from directory setup through retrieval, using the beta SDK.
---

Beta

Index V2 is in beta for enterprise users. All endpoints are available under `client.beta.*` in the SDK and may change before GA.

## Overview

Index V2 is a streamlined API for building searchable indexes over your documents. It works as a three-step model:

1. **Directory** — Upload and organize your source documents.
2. **Index** — Create an index over a directory. This triggers parsing, chunking, embedding, and vector store indexing automatically.
3. **Retrieve / Chat** — Query your indexed documents via hybrid search or a built-in chat agent.

## Prerequisites

- A [LlamaCloud account](https://cloud.llamaindex.ai) with a Pro or Enterprise plan
- An API key ([how to create one](/cloud/general/api_key/index.md))

## Install the SDK

- [Python](#tab-panel-592)
- [TypeScript](#tab-panel-593)

Terminal window

```
pip install llama-cloud
```

```
from llama_cloud import AsyncLlamaCloud


client = AsyncLlamaCloud(api_key="<your-api-key>")
```

Terminal window

```
npm install @llamaindex/llama-cloud
```

```
import LlamaCloud from "@llamaindex/llama-cloud";


const client = new LlamaCloud({
  apiKey: "<your-api-key>",
});
```

## Step 1 — Create a directory

A directory is a container for your source files. You can think of it as a folder that holds the documents you want to index.

- [Python](#tab-panel-594)
- [TypeScript](#tab-panel-595)

```
directory = await client.beta.directories.create(
    name="my-docs",
    description="Product documentation",
)
print(directory.id)  # e.g. "dir-abc123"
```

```
const directory = await client.beta.directories.create({
  name: "my-docs",
  description: "Product documentation",
});
console.log(directory.id);
```

## Step 2 — Upload files to the directory

Upload files to LlamaCloud and then add them to your directory.

- [Python](#tab-panel-596)
- [TypeScript](#tab-panel-597)

```
# Upload a file
with open("report.pdf", "rb") as f:
    file_obj = await client.files.create(file=f, purpose="user_data")


# Add the file to the directory
await client.beta.directories.files.add(
    directory.id,
    file_id=file_obj.id,
)
```

```
import fs from 'fs';


// Upload a file
const fileObj = await client.files.create({
  file: fs.createReadStream("./report.pdf"),
  purpose: "user_data",
});


// Add the file to the directory
await client.beta.directories.files.add(directory.id, {
  file_id: fileObj.id,
});
```

## Step 3 — Create an index

Creating an index kicks off an automatic pipeline that parses, chunks, embeds, and indexes all files in the source directory.

- [Python](#tab-panel-598)
- [TypeScript](#tab-panel-599)

```
index = await client.beta.indexes.create(
    source_directory_id=directory.id,
)
print(f"Index ID: {index.id}")
print(f"Status: {index.metadata['status']}")
```

```
const index = await client.beta.indexes.create({
  source_directory_id: directory.id,
});
console.log("Index ID:", index.id);
console.log("Status:", index.metadata?.status);
```

## Step 4 — Wait for the index to be ready

The index builds asynchronously. Poll until the status reaches `ready`.

- [Python](#tab-panel-600)
- [TypeScript](#tab-panel-601)

```
import asyncio


while True:
    idx = await client.beta.indexes.get(index.id)
    status = idx.metadata["status"] if idx.metadata else "unknown"


    if status == "ready":
        print("Index is ready!")
        break
    elif status == "failed":
        print("Index build failed:", idx.metadata["error_message"])
        break


    print(f"Status: {status} -- waiting...")
    await asyncio.sleep(2)
```

```
function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}


while (true) {
  const idx = await client.beta.indexes.get(index.id);
  const status = (idx.metadata?.status as string) ?? "unknown";


  if (status === "ready") {
    console.log("Index is ready!");
    break;
  } else if (status === "failed") {
    console.error("Index build failed:", idx.metadata?.error_message);
    break;
  }


  console.log(`Status: ${status} -- waiting...`);
  await sleep(2000);
}
```

## Step 5 — Retrieve

Once the index is ready, you can run hybrid search queries against it.

- [Python](#tab-panel-602)
- [TypeScript](#tab-panel-603)

```
results = await client.beta.retrieval.retrieve(
    index_id=index.id,
    query="What are the key findings?",
    top_k=5,
)


for result in results.results:
    print(f"Score: {result.score}")
    print(result.content[:200])
    print("---")
```

```
const results = await client.beta.retrieval.retrieve({
  index_id: index.id,
  query: "What are the key findings?",
  top_k: 5,
});


for (const result of results.results) {
  console.log(`Score: ${result.score}`);
  console.log(result.content.slice(0, 200));
  console.log("---");
}
```

## Next steps

- [Retrieval guide](./retrieval) — Hybrid search parameters, filtering, and reranking
- [File operations](./file_operations) — Search, grep, and read files within an index
- [Chat](./chat) — Built-in chat agent with RAG over your indexes
- [Syncing](./syncing) — Re-sync an index after adding or updating files