Getting Started with Index V2

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 with a Pro or Enterprise plan
• An API key (how to create one)

Install the SDK

Python

pip install llama-cloud

from llama_cloud import AsyncLlamaCloud

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

TypeScript

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

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

TypeScript

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

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

TypeScript

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

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

TypeScript

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

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)

TypeScript

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

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("---")

TypeScript

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 — Hybrid search parameters, filtering, and reranking
• File operations — Search, grep, and read files within an index
• Chat — Built-in chat agent with RAG over your indexes
• Syncing — Re-sync an index after adding or updating files