Getting Started with Index

Index 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.

Connecting an agent?

You don’t need to write SDK code to query an index from an MCP-compatible agent. The LlamaParse MCP exposes retrieval and file operations over your indexes as agent tools, and the Skills and Plugins page covers one-step installation for Claude Code and Codex.

Prerequisites

• A LlamaCloud account with a Starter, Pro, or Enterprise plan
• An API key (how to create one)

Install the SDK

Python

pip install llama-cloud>=2.8

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>",
});

Go

go get github.com/run-llama/llama-parse-go

import (
  "context"

  llamacloud "github.com/run-llama/llama-parse-go"
)

ctx := context.Background()

// NewClient reads LLAMA_CLOUD_API_KEY from the environment.
client := llamacloud.NewClient()

Java

implementation("ai.llamaindex:llama-cloud:1.3.0")

import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;

// fromEnv reads LLAMA_CLOUD_API_KEY from the environment.
LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

CLI

go install github.com/run-llama/llama-parse-cli/cmd/llp@latest

export LLAMA_CLOUD_API_KEY="<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);

Go

directory, err := client.Beta.Directories.New(ctx, llamacloud.BetaDirectoryNewParams{
  Name:        "my-docs",
  Description: llamacloud.String("Product documentation"),
})
if err != nil {
  log.Fatal(err)
}
fmt.Println(directory.ID) // e.g. "dir-abc123"

Java

import ai.llamaindex.llamacloud.models.beta.directories.DirectoryCreateParams;
import ai.llamaindex.llamacloud.models.beta.directories.DirectoryCreateResponse;

DirectoryCreateResponse directory = client.beta().directories().create(
    DirectoryCreateParams.builder()
        .name("my-docs")
        .description("Product documentation")
        .build());
System.out.println(directory.id()); // e.g. "dir-abc123"

CLI

DIRECTORY_ID=$(llp beta:directories create \
  --name "my-docs" \
  --description "Product documentation" | jq -r '.id')

echo "$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,
});

Go

// Upload a file
f, err := os.Open("report.pdf")
if err != nil {
  log.Fatal(err)
}
defer f.Close()

fileObj, err := client.Files.New(ctx, llamacloud.FileNewParams{
  File:    f,
  Purpose: "user_data",
})
if err != nil {
  log.Fatal(err)
}

// Add the file to the directory
_, err = client.Beta.Directories.Files.Add(ctx, directory.ID, llamacloud.BetaDirectoryFileAddParams{
  FileID: fileObj.ID,
})
if err != nil {
  log.Fatal(err)
}

Java

import java.nio.file.Paths;

import ai.llamaindex.llamacloud.models.beta.directories.files.FileAddParams;
import ai.llamaindex.llamacloud.models.files.FileCreateParams;
import ai.llamaindex.llamacloud.models.files.FileCreateResponse;

// Upload a file
FileCreateResponse fileObj = client.files().create(
    FileCreateParams.builder()
        .file(Paths.get("report.pdf"))
        .purpose("user_data")
        .build());

// Add the file to the directory
client.beta().directories().files().add(
    directory.id(),
    FileAddParams.builder()
        .fileId(fileObj.id())
        .build());

CLI

# Upload a file
FILE_ID=$(llp files create \
  --file ./report.pdf \
  --purpose user_data | jq -r '.id')

# Add the file to the directory
llp beta:directories:files add \
  --directory-id "$DIRECTORY_ID" \
  --file-id "$FILE_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);

Go

index, err := client.Beta.Indexes.New(ctx, llamacloud.BetaIndexNewParams{
  SourceDirectoryID: directory.ID,
})
if err != nil {
  log.Fatal(err)
}
fmt.Println("Index ID:", index.ID)
fmt.Println("Status:", index.Metadata["status"])

Java

import ai.llamaindex.llamacloud.core.JsonValue;
import ai.llamaindex.llamacloud.models.beta.indexes.IndexCreateParams;
import ai.llamaindex.llamacloud.models.beta.indexes.IndexCreateResponse;

IndexCreateResponse index = client.beta().indexes().create(
    IndexCreateParams.builder()
        .sourceDirectoryId(directory.id())
        .build());
System.out.println("Index ID: " + index.id());
System.out.println("Status: " + index.metadata()
    .map(m -> m._additionalProperties().get("status"))
    .flatMap(JsonValue::asString)
    .orElse("unknown"));

CLI

INDEX_ID=$(llp beta:indexes create \
  --source-directory-id "$DIRECTORY_ID" | jq -r '.id')

echo "Index ID: $INDEX_ID"

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);
}

Go

for {
  idx, err := client.Beta.Indexes.Get(ctx, index.ID, llamacloud.BetaIndexGetParams{})
  if err != nil {
    log.Fatal(err)
  }

  status, ok := idx.Metadata["status"].(string)
  if !ok {
    status = "unknown"
  }

  if status == "ready" {
    fmt.Println("Index is ready!")
    break
  } else if status == "failed" {
    fmt.Println("Index build failed:", idx.Metadata["error_message"])
    break
  }

  fmt.Printf("Status: %s -- waiting...\n", status)
  time.Sleep(2 * time.Second)
}

Java

import ai.llamaindex.llamacloud.core.JsonValue;
import ai.llamaindex.llamacloud.models.beta.indexes.IndexGetResponse;

while (true) {
    IndexGetResponse idx = client.beta().indexes().get(index.id());
    String status = idx.metadata()
        .map(m -> m._additionalProperties().get("status"))
        .flatMap(JsonValue::asString)
        .orElse("unknown");

    if (status.equals("ready")) {
        System.out.println("Index is ready!");
        break;
    } else if (status.equals("failed")) {
        System.out.println("Index build failed: " + idx.metadata()
            .map(m -> m._additionalProperties().get("error_message"))
            .flatMap(JsonValue::asString)
            .orElse(""));
        break;
    }

    System.out.println("Status: " + status + " -- waiting...");
    Thread.sleep(2000);
}

CLI

while true; do
  METADATA=$(llp beta:indexes get --index-id "$INDEX_ID" | jq -c '.metadata // {}')
  STATUS=$(echo "$METADATA" | jq -r '.status // "unknown"')

  if [ "$STATUS" = "ready" ]; then
    echo "Index is ready!"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Index build failed: $(echo "$METADATA" | jq -r '.error_message // ""')"
    break
  fi

  echo "Status: $STATUS -- waiting..."
  sleep 2
done

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

Go

results, err := client.Beta.Retrieval.Get(ctx, llamacloud.BetaRetrievalGetParams{
  IndexID: index.ID,
  Query:   "What are the key findings?",
  TopK:    llamacloud.Int(5),
})
if err != nil {
  log.Fatal(err)
}

for _, result := range results.Results {
  fmt.Printf("Score: %v\n", result.Score)
  content := result.Content
  if len(content) > 200 {
    content = content[:200]
  }
  fmt.Println(content)
  fmt.Println("---")
}

Java

import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalRetrieveParams;
import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalRetrieveResponse;

RetrievalRetrieveResponse results = client.beta().retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId(index.id())
        .query("What are the key findings?")
        .topK(5)
        .build());

for (RetrievalRetrieveResponse.Result result : results.results()) {
    System.out.println("Score: " + result.score().orElse(null));
    String content = result.content();
    System.out.println(content.substring(0, Math.min(200, content.length())));
    System.out.println("---");
}

CLI

llp beta:retrieval retrieve \
  --index-id "$INDEX_ID" \
  --query "What are the key findings?" \
  --top-k 5 \
  | jq -r '.results[] | "Score: \(.score)\n\(.content[0:200])\n---"'

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
• LlamaParse MCP — Let MCP-compatible agents discover, search, and retrieve from your indexes