Quick Start: Parse a PDF & Interpret Outputs

Use Parse to process a single PDF and interpret the most common output views: text, markdown, items, and metadata. In this example, we’re using the 2024 Executive Summary by the Bureau of the Fiscal Service

1. Setup & Connect to Parse

First, set your API key as an environment variable so the SDKs and CLI pick it up automatically:

export LLAMA_CLOUD_API_KEY="llx-..."

Then install the SDK for your language and initialize a client:

Python

pip install "llama-cloud>=2.8"

from llama_cloud import LlamaCloud

client = LlamaCloud()  # reads LLAMA_CLOUD_API_KEY from the environment

TypeScript

npm install @llamaindex/llama-cloud

import LlamaCloud from '@llamaindex/llama-cloud';

const client = new LlamaCloud(); // reads LLAMA_CLOUD_API_KEY from the environment

Go

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

import (
  "context"

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

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

Java

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

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

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

llp reads LLAMA_CLOUD_API_KEY from the environment (or pass --api-key on any command).

2. Upload and Parse a PDF

Before we parse, we connect once to Parse with a client and choose a tier. Tiers control the quality/latency/cost trade-off of Parse:

• “fast” - the fastest tier with basic parsing capabilities.
• “cost_effective” – lower cost and latency for simpler documents.
• “agentic” – default tier for most use cases.
• “agentic_plus” – highest fidelity for very complex layouts.

Next we upload the PDF and parse it.
The expand parameter tells Parse which output views to return inline with the job result. In this example we ask for:

• “text” – plain text per page
• “markdown” – markdown view
• “items” – structured layout tree
• “metadata” – page/job metadata (including confidence)

Python

# 1) Upload the file
file = client.files.create(
    file="executive-summary-2024.pdf",
    purpose="parse",
)

# 2) Parse it, requesting all four inline views
result = client.parsing.parse(
    file_id=file.id,
    tier="agentic",
    version="latest",
    expand=["markdown", "text", "metadata", "items"],
)

TypeScript

import fs from 'fs';

// 1) Upload the file
const file = await client.files.create({
  file: fs.createReadStream('executive-summary-2024.pdf'),
  purpose: 'parse',
});

// 2) Parse it, requesting all four inline views
const result = await client.parsing.parse({
  file_id: file.id,
  tier: 'agentic',
  version: 'latest',
  expand: ['markdown', 'text', 'metadata', 'items'],
});

Go

// 1) Upload the file
f, err := os.Open("executive-summary-2024.pdf")
if err != nil {
  log.Fatal(err)
}
defer f.Close()

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

// 2) Create the parse job
job, err := client.Parsing.New(ctx, llamacloud.ParsingNewParams{
  FileID:  llamacloud.String(file.ID),
  Tier:    llamacloud.ParsingNewParamsTierAgentic,
  Version: llamacloud.ParsingNewParamsVersionLatest,
})
if err != nil {
  log.Fatal(err)
}

// 3) expand is a GET parameter in Go — poll, then request all four views at once
getParams := llamacloud.ParsingGetParams{Expand: []string{"markdown", "text", "metadata", "items"}}
result, err := client.Parsing.Get(ctx, job.ID, getParams)
if err != nil {
  log.Fatal(err)
}
for result.Job.Status != "COMPLETED" && result.Job.Status != "FAILED" && result.Job.Status != "CANCELLED" {
  time.Sleep(2 * time.Second)
  result, err = client.Parsing.Get(ctx, job.ID, getParams)
  if err != nil {
    log.Fatal(err)
  }
}
if result.Job.Status != "COMPLETED" {
  log.Fatalf("parse ended as %s", result.Job.Status)
}

Java

// 1) Upload the file
FileCreateResponse file = client.files().create(FileCreateParams.builder()
        .file(Paths.get("executive-summary-2024.pdf"))
        .purpose("parse")
        .build());

// 2) Create the parse job
ParsingCreateResponse job = client.parsing().create(ParsingCreateParams.builder()
        .fileId(file.id())
        .tier(ParsingCreateParams.Tier.AGENTIC)
        .version(ParsingCreateParams.Version.LATEST)
        .build());

// 3) expand is a query parameter in Java — poll, then request all four views at once
ParsingGetParams getParams = ParsingGetParams.builder()
        .jobId(job.id())
        .addExpand("markdown")
        .addExpand("text")
        .addExpand("metadata")
        .addExpand("items")
        .build();

ParsingGetResponse result = client.parsing().get(getParams);
while (!result.job().status().equals(ParsingGetResponse.Job.Status.COMPLETED)
        && !result.job().status().equals(ParsingGetResponse.Job.Status.FAILED)
        && !result.job().status().equals(ParsingGetResponse.Job.Status.CANCELLED)) {
    Thread.sleep(2000);
    result = client.parsing().get(getParams);
}
if (!result.job().status().equals(ParsingGetResponse.Job.Status.COMPLETED)) {
    throw new RuntimeException("parse ended as " + result.job().status());
}

CLI

# 1) Upload the file
FILE_ID=$(llp files create \
  --file ./executive-summary-2024.pdf \
  --purpose parse | jq -r '.id')

# 2) Start a parse job
JOB_ID=$(llp parsing create \
  --file-id "$FILE_ID" \
  --tier agentic \
  --version latest | jq -r '.id')

# 3) Poll until the job reaches a terminal status
while true; do
  STATUS=$(llp parsing get --job-id "$JOB_ID" | jq -r '.job.status')
  case "$STATUS" in COMPLETED|FAILED|CANCELLED) break ;; esac
  sleep 2
done

# expand is a query parameter — request all four views at once and save the result
llp parsing get --job-id "$JOB_ID" \
  --expand markdown \
  --expand text \
  --expand metadata \
  --expand items > result.json

The result now contains all four views of the same parsed document. In Go, Java, and the CLI, expand is a query parameter on the result fetch, so those languages create the job, poll until it finishes, then request the four views in a single get.

Choosing expand outputs

You can request one or many expand values at once. More expand options mean a larger response and slightly higher latency, so in production you can request only what your pipeline needs (for example, “text” + “metadata” or “markdown” only).

3. Interpreting the Outputs

Text view (result.text)

The text view gives you clean, flattened text per page – good for basic search or feeding into downstream retrieval.

Python

first_page_text = result.text.pages[0].text
print(first_page_text)

TypeScript

const firstPageText = result.text.pages[0].text;
console.log(firstPageText);

Go

firstPageText := result.Text.Pages[0].Text
fmt.Println(firstPageText)

Java

String firstPageText = result.text().get().pages().get(0).text();
System.out.println(firstPageText);

CLI

jq -r '.text.pages[0].text' result.json

You’ll see the plain text from the first page:

1                  EXECUTIVE SUMMARY TO THE FY 2024 FINANCIAL REPORT OF THE U.S. GOVERNMENT

                                            NATION BY THE NUMBERS
                                                A Snapshot of
                               The Government's Financial Position & Condition             2023*
                                                                            2024
                                  Financial Measures (Dollars in Billions):
     Net Cost:
      Gross Costs                                                $          (7,772.2) $            (7,661.7)
      Less: Earned Revenue                                                  652.9 $                539.5
      Gain/(Loss) from Changes in Assumptions                    $          (283.6) $                (760.6)
     Total Net Cost                                              $          (7,402.9)              (7,882.8)
                                                                 $          4,977.9 $
     Less: Total Tax and Other Unearned Revenues                                      $     4,465.6
     Net Operating Cost                                          $          (2,425.0) $     (3,417.2)
     Budget Deficit                                              $          (1,832.8) $     (1,695.2)
     Assets, comprised of:                                      20          1,177.7                922.2
      Cash and Other Monetary Assets                                                 $
      Inventory and Related Property, Net                                   447.3 $                423.0
      Loans Receivable, Net                                      1,751.0 $                   1,695.1
      Property, Plant, and Equipment, Net                        1,313.0 $                   1,235.0
      Other                                                                 973.1     $      1,143.8
     Total Assets                                                $            5,662.1 $      5,419.1
     Less: Liabilities, comprised of:                                       (28,338.9) $     (26,347.7)
      Federal Debt and Interest Payable                          $
      Federal Employee and Veteran Benefits Payable             $ (15,033.4)$                     (14,347.6)
      Other                                                      $          (2,173.6)              (2,203.0)
                                                                                     $
     Total Liabilities                                           $ (45,545.9)$                    (42,898.3)
     Net Position                                                $         (39,883.8) $      (37,479.2)
                               Sustainability Measures (Dollars in Trillions):               (78.4)
     Social Insurance Net Expenditures                           $             (78.3) $
     Total Federal Non-Interest Net Expenditures                 $             (72.7) $      (73.2)
                                   Sustainability Measures as Percent GDP:                   (4.4%)
     Social Insurance Net Expenditures2                            (4.2%)
     Total Federal Non-Interest Net Expenditures                   (3.6%)                    (3.8%)
     Fiscal Gap3                                                   (4.3%)                    (4.5%)

      The government's net position is calculated in accordance with federal accounting standards. Per
      these standards, net position does not include the financial value of the government's sovereign power
      to tax, regulate commerce, or set monetary policy, or the value of nonoperational resources, such as
      national and natural resources, for which the government is a steward.
      Pursuant to federal accounting standards, for SOsl reporting, the federal government's social
      insurance programs include Social Security; Medicare Parts A, B, and D; DOL's Black Lung program;
      and the RRB.
      To prevent the debt-to-GDP ratio from rising over the next 75 years, a combination of non-interest
      spending reductions and receipts increases that amount to 4.3 percent of GDP on average is needed
      (4.5 percent of GDP on average in FY 2023). See Financial Statement Note 24.
      Change in presentation (see Financial Statement Note 1.W).

Markdown view (result.markdown)

The markdown view preserves structure such as headings, lists, and tables. This is the most LLM-friendly representation in many RAG pipelines.

Python

first_page_markdown = result.markdown.pages[0].markdown
print(first_page_markdown)

TypeScript

const firstPageMarkdown = result.markdown.pages[0].markdown;
console.log(firstPageMarkdown);

Go

firstPageMarkdown := result.Markdown.Pages[0].Markdown
fmt.Println(firstPageMarkdown)

Java

String firstPageMarkdown = result.markdown().get().pages().get(0).asMarkdownResult().markdown();
System.out.println(firstPageMarkdown);

CLI

jq -r '.markdown.pages[0].markdown' result.json

You’ll see content similar to the original document, but expressed as markdown (e.g. # Headings, bullet lists, and pipe tables).

# NATION BY THE NUMBERS
## A Snapshot of The Government's Financial Position & Condition

<table>
  <thead>
    <tr>
        <th colspan="3">Financial Measures (Dollars in Billions):</th>
    </tr>
    <tr>
        <th></th>
        <th>2024</th>
        <th>2023*</th>
    </tr>
  </thead>
  <tbody>
    <tr>
        <td>Net Cost:</td>
        <td></td>
        <td></td>
    </tr>
    <tr>
        <td>Gross Costs</td>
        <td>$ (7,772.2)</td>
        <td>$ (7,661.7)</td>
    </tr>
    <tr>
        <td>Less: Earned Revenue</td>
        <td>$ 652.9</td>
        <td>$ 539.5</td>
    </tr>
    <tr>
        <td>Gain/(Loss) from Changes in Assumptions</td>
        <td>$ (283.6)</td>
        <td>$ (760.6)</td>
    </tr>
    <tr>
        <td>Total Net Cost</td>
        <td>$ (7,402.9)</td>
        <td>$ (7,882.8)</td>
    </tr>
    <tr>
        <td>Less: Total Tax and Other Unearned Revenues</td>
        <td>$ 4,977.9</td>
        <td>$ 4,465.6</td>
    </tr>
    <tr>
        <td>Net Operating Cost</td>
        <td>$ (2,425.0)</td>
        <td>$ (3,417.2)</td>
    </tr>
    <tr>
        <td>Budget Deficit</td>
        <td>$ (1,832.8)</td>
        <td>$ (1,695.2)</td>
    </tr>
    <tr>
        <td>Assets, comprised of:</td>
        <td></td>
        <td></td>
    </tr>
    <tr>
        <td>Cash and Other Monetary Assets</td>
        <td>$ 1,177.7</td>
        <td>$ 922.2</td>
    </tr>
    <tr>
        <td>Inventory and Related Property, Net</td>
        <td>$ 447.3</td>
        <td>$ 423.0</td>
    </tr>
    <tr>
        <td>Loans Receivable, Net</td>
        <td>$ 1,751.0</td>
        <td>$ 1,695.1</td>
    </tr>
    <tr>
        <td>Property, Plant, and Equipment, Net</td>
        <td>$ 1,313.0</td>
        <td>$ 1,235.0</td>
    </tr>
    <tr>
        <td>Other</td>
        <td>$ 973.1</td>
        <td>$ 1,143.8</td>
    </tr>
    <tr>
        <td>Total Assets</td>
        <td>$ 5,662.1</td>
        <td>$ 5,419.1</td>
    </tr>
    <tr>
        <td>Less: Liabilities, comprised of:</td>
        <td></td>
        <td></td>
    </tr>
    <tr>
        <td>Federal Debt and Interest Payable</td>
        <td>$ (28,338.9)</td>
        <td>$ (26,347.7)</td>
    </tr>
    <tr>
        <td>Federal Employee and Veteran Benefits Payable</td>
        <td>$ (15,033.4)</td>
        <td>$ (14,347.6)</td>
    </tr>
    <tr>
        <td>Other</td>
        <td>$ (2,173.6)</td>
        <td>$ (2,203.0)</td>
    </tr>
    <tr>
        <td>Total Liabilities</td>
        <td>$ (45,545.9)</td>
        <td>$ (42,898.3)</td>
    </tr>
    <tr>
        <td>Net Position¹</td>
        <td>$ (39,883.8)</td>
        <td>$ (37,479.2)</td>
    </tr>
    <tr>
        <td colspan="3">Sustainability Measures (Dollars in Trillions):</td>
    </tr>
    <tr>
        <td>Social Insurance Net Expenditures</td>
        <td>$ (78.3)</td>
        <td>$ (78.4)</td>
    </tr>
    <tr>
        <td>Total Federal Non-Interest Net Expenditures</td>
        <td>$ (72.7)</td>
        <td>$ (73.2)</td>
    </tr>
    <tr>
        <td colspan="3">Sustainability Measures as Percent GDP:</td>
    </tr>
    <tr>
        <td>Social Insurance Net Expenditures²</td>
        <td>(4.2%)</td>
        <td>(4.4%)</td>
    </tr>
    <tr>
        <td>Total Federal Non-Interest Net Expenditures</td>
        <td>(3.6%)</td>
        <td>(3.8%)</td>
    </tr>
    <tr>
        <td>Fiscal Gap³</td>
        <td>(4.3%)</td>
        <td>(4.5%)</td>
    </tr>
  </tbody>
</table>

> ¹ The government's net position is calculated in accordance with federal accounting standards. Per these standards, net position does not include the financial value of the government's sovereign power to tax, regulate commerce, or set monetary policy, or the value of nonoperational resources, such as national and natural resources, for which the government is a steward.
>
> ² Pursuant to federal accounting standards, for SOSI reporting, the federal government's social insurance programs include Social Security; Medicare Parts A, B, and D; DOL's Black Lung program; and the RRB.
>
> ³ To prevent the debt-to-GDP ratio from rising over the next 75 years, a combination of non-interest spending reductions and receipts increases that amount to 4.3 percent of GDP on average is needed (4.5 percent of GDP on average in FY 2023). See Financial Statement Note 24.
>
> \* Change in presentation (see Financial Statement Note 1.W).

Items view (result.items)

The items view is a structured tree of elements on each page: paragraphs, tables, figures, etc. Use this when you need fine-grained layout-aware processing.

Python

first_page_items = result.items.pages[0].items

for item in first_page_items[:5]:
    print(item.type, item)

TypeScript

const firstPageItems = result.items.pages[0].items;

for (const item of firstPageItems.slice(0, 5)) {
  console.log(item.type, item);
}

Go

firstPageItems := result.Items.Pages[0].Items

for i, item := range firstPageItems {
  if i >= 5 {
    break
  }
  fmt.Printf("%s: %s\n", item.Type, item.Md)
}

Java

ParsingGetResponse.Items.Page.StructuredResultPage firstPage =
        result.items().get().pages().get(0).asStructuredResult();

for (ParsingGetResponse.Items.Page.StructuredResultPage.Item item : firstPage.items()) {
    if (item.isHeader()) {
        System.out.println("header: " + item.asHeader().md());
    } else if (item.isHeading()) {
        System.out.println("heading: " + item.asHeading().md());
    } else if (item.isTable()) {
        System.out.println("table: " + item.asTable().rows().size() + " rows");
    } else if (item.isText()) {
        System.out.println("text: " + item.asText().md());
    } else if (item.isImage()) {
        System.out.println("image: " + item.asImage().md());
    }
}

CLI

jq -r '.items.pages[0].items[0:5][] | .type' result.json

Typical type values include header, heading, text, table, and image. Tables carry row data; images can reference figures or charts.

// Each item carries a `type`, a markdown `md` string, and layout `bbox`es.
// Table items also include `rows`, `csv`, and `html`; image items reference figures or charts.
[
  { "type": "header",  "md": "1 EXECUTIVE SUMMARY TO THE FY 2024 FINANCIAL REPORT OF THE U.S. GOVERNMENT" },
  { "type": "heading", "level": 1, "md": "# NATION BY THE NUMBERS" },
  { "type": "heading", "level": 2, "md": "## A Snapshot of The Government's Financial Position & Condition" },
  { "type": "table",   "rows": [["Financial Measures (Dollars in Billions):", "2024", "2023*"], ["Gross Costs", "$ (7,772.2)", "$ (7,661.7)"]] },
  { "type": "text",    "md": "¹ The government's net position is calculated in accordance with federal accounting standards..." }
]

Metadata view (result.metadata)

The metadata view exposes page-level and job-level metadata, such as confidence scores and presentation-specific data.

Python

first_page_meta = result.metadata.pages[0]

print("Page number:", first_page_meta.page_number)
print("Confidence:", first_page_meta.confidence)

TypeScript

const firstPageMeta = result.metadata.pages[0];

console.log("Page number:", firstPageMeta.page_number);
console.log("Confidence:", firstPageMeta.confidence);

Go

firstPageMeta := result.Metadata.Pages[0]

fmt.Println("Page number:", firstPageMeta.PageNumber)
fmt.Println("Confidence:", firstPageMeta.Confidence)

Java

ParsingGetResponse.Metadata.Page firstPageMeta = result.metadata().get().pages().get(0);

System.out.println("Page number: " + firstPageMeta.pageNumber());
System.out.println("Confidence: " + firstPageMeta.confidence().orElse(null));

CLI

jq -r '.metadata.pages[0] | "Page number: \(.page_number)\nConfidence: \(.confidence)"' result.json

• page_number tells you which page the metadata corresponds to.
• confidence is a relative score (0–1) for how confident the parser is about that page.
• Other fields (e.g. slide speaker_notes for presentations) are available depending on the input type.

Page number: 1
Confidence: 0.985

The full per-page metadata object carries the same fields across every language — page number, confidence, and presentation-specific flags:

{
  "page_number": 1,
  "confidence": 0.985,
  "cost_optimized": false,
  "original_orientation_angle": 0,
  "printed_page_number": null,
  "slide_section_name": null,
  "speaker_notes": null,
  "triggered_auto_mode": false
}

Together, these four views let you:

• Use text or markdown directly in LLM pipelines.
• Use items when you need tables, figures, or explicit layout.
• Use metadata for quality checks, routing low-confidence pages to humans, or analytics.