Getting Started

Quickstart

Upload a document

First, upload a PDF using the Files API.

Python

Install the Python SDK if you haven’t already:

pip install llama-cloud>=2.8

Then upload your file:

from llama_cloud import LlamaCloud

client = LlamaCloud(api_key="LLAMA_CLOUD_API_KEY")

file_obj = client.files.create(file="path/to/your/file.pdf", purpose="split")
print(file_obj.id)

TypeScript

Install the TypeScript SDK if you haven’t already:

npm install @llamaindex/llama-cloud

Then upload your file:

import fs from "fs";
import { LlamaCloud } from "@llamaindex/llama-cloud";

const client = new LlamaCloud({
  apiKey: "LLAMA_CLOUD_API_KEY",
});

const fileObj = await client.files.create({
  file: fs.createReadStream('path/to/your/file.pdf'),
  purpose: 'split',
});
console.log(fileObj.id);

Go

Install the Go SDK if you haven’t already:

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

Then upload your file:

package main

import (
  "context"
  "fmt"
  "log"
  "os"

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

func main() {
  client := llamacloud.NewClient()

  f, err := os.Open("path/to/your/file.pdf")
  if err != nil {
    log.Fatal(err)
  }
  defer f.Close()

  fileObj, err := client.Files.New(context.TODO(), llamacloud.FileNewParams{
    File:    f,
    Purpose: "split",
  })
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(fileObj.ID)
}

Java

Install the Java SDK if you haven’t already:

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

Then upload your file:

import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;
import ai.llamaindex.llamacloud.models.files.FileCreateParams;
import ai.llamaindex.llamacloud.models.files.FileCreateResponse;
import java.nio.file.Paths;

LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

FileCreateResponse fileObj = client.files().create(
    FileCreateParams.builder()
        .file(Paths.get("path/to/your/file.pdf"))
        .purpose("split")
        .build()
);
System.out.println(fileObj.id());

CLI

Install the CLI if you haven’t already:

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

Then upload your file:

llp files create \
  --file path/to/your/file.pdf \
  --purpose split

cURL

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/files' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -F 'purpose=split' \
  -F 'file=@/path/to/your/file.pdf;type=application/pdf'

Save the returned id as your FILE_ID.

Create a split job

Create a split job with your file ID and category definitions:

Python

job = client.beta.split.create(
  document_input={"type": "file_id", "value": file_obj.id},
  configuration={
    "categories": [
      {
        "name": "invoice",
        "description": "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
      },
      {
        "name": "contract",
        "description": "A legal agreement between parties outlining terms, conditions, obligations, and signatures"
      }
    ]
  },
)

TypeScript

const job = await client.beta.split.create({
  document_input: { type: "file_id", value: fileObj.id },
  configuration: {
    categories: [
      {
        name: "invoice",
        description: "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
      },
      {
        name: "contract",
        description: "A legal agreement between parties outlining terms, conditions, obligations, and signatures"
      }
    ]
  },
});

Go

job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  DocumentInput: llamacloud.SplitDocumentInputParam{
    Type:  "file_id",
    Value: fileObj.ID,
  },
  Configuration: llamacloud.BetaSplitNewParamsConfiguration{
    Categories: []llamacloud.SplitCategoryParam{
      {
        Name:        "invoice",
        Description: llamacloud.String("A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"),
      },
      {
        Name:        "contract",
        Description: llamacloud.String("A legal agreement between parties outlining terms, conditions, obligations, and signatures"),
      },
    },
  },
})
if err != nil {
  log.Fatal(err)
}

Java

import ai.llamaindex.llamacloud.models.beta.split.SplitCategory;
import ai.llamaindex.llamacloud.models.beta.split.SplitCreateParams;
import ai.llamaindex.llamacloud.models.beta.split.SplitCreateResponse;
import ai.llamaindex.llamacloud.models.beta.split.SplitDocumentInput;

SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        .documentInput(
            SplitDocumentInput.builder()
                .type("file_id")
                .value(fileObj.id())
                .build())
        .configuration(
            SplitCreateParams.Configuration.builder()
                .addCategory(
                    SplitCategory.builder()
                        .name("invoice")
                        .description("A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms")
                        .build())
                .addCategory(
                    SplitCategory.builder()
                        .name("contract")
                        .description("A legal agreement between parties outlining terms, conditions, obligations, and signatures")
                        .build())
                .build())
        .build()
);

CLI

llp beta:split create \
  --document-input "{type: file_id, value: $FILE_ID}" \
  --configuration '{categories: [{name: invoice, description: "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"}, {name: contract, description: "A legal agreement between parties outlining terms, conditions, obligations, and signatures"}]}'

cURL

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "document_input": {
      "type": "file_id",
      "value": "YOUR_FILE_ID"
    },
    "configuration": {
      "categories": [
        {
          "name": "invoice",
          "description": "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
        },
        {
          "name": "contract",
          "description": "A legal agreement between parties outlining terms, conditions, obligations, and signatures"
        }
      ]
    }
  }'

The response includes the job ID and initial status:

{
  "id": "spl-abc123...",
  "status": "pending"
}

Poll for job completion

Jobs are processed asynchronously. Poll the status until it reaches a terminal state — completed, failed, or cancelled:

Python

completed_job = client.beta.split.wait_for_completion(
    job.id,
    polling_interval=1.0,
    verbose=True,
)

TypeScript

const completedJob = await client.beta.split.waitForCompletion(
  job.id,
  { pollingInterval: 1.0, verbose: true, }
);

Go

completedJob, err := client.Beta.Split.Get(context.TODO(), job.ID, llamacloud.BetaSplitGetParams{})
if err != nil {
  log.Fatal(err)
}
for completedJob.Status != "completed" &&
  completedJob.Status != "failed" &&
  completedJob.Status != "cancelled" {
  time.Sleep(2 * time.Second)
  completedJob, err = client.Beta.Split.Get(context.TODO(), job.ID, llamacloud.BetaSplitGetParams{})
  if err != nil {
    log.Fatal(err)
  }
}

Java

import ai.llamaindex.llamacloud.models.beta.split.SplitGetResponse;

SplitGetResponse completedJob = client.beta().split().get(job.id());
while (!completedJob.status().equals("completed")
    && !completedJob.status().equals("failed")
    && !completedJob.status().equals("cancelled")) {
    Thread.sleep(2000);
    completedJob = client.beta().split().get(job.id());
}

CLI

while true; do
  STATUS=$(llp beta:split get "$JOB_ID" | jq -r '.status')
  case "$STATUS" in
    completed|failed|cancelled) break ;;
  esac
  sleep 2
done

llp beta:split get "$JOB_ID"

cURL

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs/YOUR_JOB_ID' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

Get the results

When the job completes successfully, the response includes the segmentation results:

{
  "id": "spl-abc123...",
  "status": "completed",
  "result": {
    "segments": [
      {
        "category": "invoice",
        "pages": [1, 2, 3],
        "confidence_category": "high"
      },
      {
        "category": "contract",
        "pages": [4, 5, 6, 7, 8],
        "confidence_category": "high"
      }
    ]
  }
}

Each segment contains:

• category: The assigned category name
• pages: Array of page numbers (1-indexed) belonging to this segment
• confidence_category: Confidence level (high, medium, or low)

Advanced Options

Uncategorized pages

By default, pages that don’t match any defined category are grouped as uncategorized and included in the results. You can control this behavior with the allow_uncategorized option in splitting_strategy:

Value	Behavior
"include" (default)	Pages that don’t match any category will be grouped as uncategorized and included in results
"forbid"	All pages must be assigned to a defined category
"omit"	Pages that don’t match any category will not appear in results

For example, to exclude uncategorized pages from results:

Python

job = client.beta.split.create(
  document_input={"type": "file_id", "value": file_obj.id},
  configuration={
    "categories": [
      {
        "name": "invoice",
        "description": "A commercial document requesting payment for goods or services"
      }
    ],
    "splitting_strategy": {"allow_uncategorized": "omit"}
  },
)

TypeScript

const job = await client.beta.split.create({
  document_input: { type: "file_id", value: fileObj.id },
  configuration: {
    categories: [
      {
        name: "invoice",
        description: "A commercial document requesting payment for goods or services"
      }
    ],
    splitting_strategy: { allow_uncategorized: "omit" }
  },
});

Go

job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  DocumentInput: llamacloud.SplitDocumentInputParam{
    Type:  "file_id",
    Value: fileObj.ID,
  },
  Configuration: llamacloud.BetaSplitNewParamsConfiguration{
    Categories: []llamacloud.SplitCategoryParam{
      {
        Name:        "invoice",
        Description: llamacloud.String("A commercial document requesting payment for goods or services"),
      },
    },
    SplittingStrategy: llamacloud.BetaSplitNewParamsConfigurationSplittingStrategy{
      AllowUncategorized: "omit",
    },
  },
})
if err != nil {
  log.Fatal(err)
}

Java

SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        .documentInput(
            SplitDocumentInput.builder()
                .type("file_id")
                .value(fileObj.id())
                .build())
        .configuration(
            SplitCreateParams.Configuration.builder()
                .addCategory(
                    SplitCategory.builder()
                        .name("invoice")
                        .description("A commercial document requesting payment for goods or services")
                        .build())
                .splittingStrategy(
                    SplitCreateParams.Configuration.SplittingStrategy.builder()
                        .allowUncategorized(
                            SplitCreateParams.Configuration.SplittingStrategy.AllowUncategorized.OMIT)
                        .build())
                .build())
        .build()
);

CLI

llp beta:split create \
  --document-input "{type: file_id, value: $FILE_ID}" \
  --configuration '{categories: [{name: invoice, description: "A commercial document requesting payment for goods or services"}], splitting_strategy: {allow_uncategorized: omit}}'

cURL

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "document_input": {
      "type": "file_id",
      "value": "YOUR_FILE_ID"
    },
    "configuration": {
      "categories": [
        {
          "name": "invoice",
          "description": "A commercial document requesting payment for goods or services"
        }
      ],
      "splitting_strategy": {
        "allow_uncategorized": "omit"
      }
    }
  }'

With "omit", pages that don’t match invoice will not appear in the response. To force all pages into defined categories instead, set allow_uncategorized to "forbid".

Using project IDs

If you’re working within a specific project, include the project_id query parameter:

Python

job = client.beta.split.create(
  ...,
  project_id="YOUR_PROJECT_ID"
)

TypeScript

const job = await client.beta.split.create({
  ...,
  project_id: "YOUR_PROJECT_ID"
});

Go

job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  // ...
  ProjectID: llamacloud.String("YOUR_PROJECT_ID"),
})

Java

SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        // ...
        .projectId("YOUR_PROJECT_ID")
        .build()
);

CLI

llp beta:split create \
  --project-id YOUR_PROJECT_ID \
  ...

cURL

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs?project_id=YOUR_PROJECT_ID' \
  ...

Full API Documentation

This is a subset of the available endpoints to help you get started.

You can see all available endpoints in our full API documentation.