Cost Optimizer

The cost optimizer reduces parsing costs by intelligently routing pages to different processing tiers based on their content complexity. Simple pages (plain text, single-column layouts) are processed with the cheaper cost_effective tier, while complex pages (tables, charts, multi-column layouts, annotated images) are processed with your selected premium tier.

How It Works

When cost optimizer is enabled, each page in your document is analyzed during the layout detection phase and classified as either cost-optimizable or non-cost-optimizable:

• Cost-optimizable pages are processed using the cost_effective tier (cheaper model)
• Non-cost-optimizable pages are processed using your original tier (agentic or agentic_plus)

Both groups are processed in parallel, so there is no significant impact on total parsing time.

Pages That Cannot Be Cost-Optimized

A page is routed to the premium tier if it contains any of the following:

• Tables or charts detected in the layout
• Multi-column text layout (text blocks on both left and right halves of the page)
• Images with inline image embedding enabled (inline_images_in_markdown: true)
• Images with significant overlapping text (3+ text boxes with >50% overlap on an image)
• Complex figure types detected with high confidence: maps, flow charts, chemistry diagrams (molecular or Markush structures), or other non-standard figures

Theses criterias evolve over time, our goal is that we will use the cheaper model whenever we can do it wihtout degrading final output quality.

Requirements

Cost optimizer is only available with the agentic and agentic_plus tiers. It cannot be used with the fast or cost_effective tiers.

Configuration

{
  "tier": "agentic",
  "version": "latest",
  "cost_optimizer": {
    "enable": true
  }
}

Output Metadata

When cost optimizer is enabled, the per-page metadata in the response includes a cost_optimized field indicating whether each page was processed with the cheaper tier:

{
  "pages": [
    {
      "page": 1,
      "cost_optimized": true
    },
    {
      "page": 2,
      "cost_optimized": false
    }
  ]
}

Pages where cost_optimized is true were processed with the cost_effective tier. Pages where it is false were processed with your selected premium tier.

Complete API Request Example

cURL

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v2/parse' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  --data '{
    "file_id": "<file_id>",
    "tier": "agentic",
    "version": "latest",
    "cost_optimizer": {
      "enable": true
    }
  }'

Python

from llama_cloud import LlamaCloud

client = LlamaCloud(api_key="LLAMA_CLOUD_API_KEY")

result = client.parsing.parse(
    upload_file="example_file.pdf",
    tier="agentic",
    version="latest",
    cost_optimizer={"enable": True},
    expand=["markdown"],
)

TypeScript

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

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

const result = await client.parsing.parse({
  upload_file: fs.createReadStream('example_file.pdf'),
  tier: "agentic",
  version: "latest",
  cost_optimizer: { enable: true },
  expand: ["markdown"],
});