Multifile Extraction

Multifile extraction lets you run a single extraction over a collection of files with a shared context. Useful when a field’s value must be chosen from the best among a variety of sources, or when values are derived from multiple files.

Example 1: A contract contains a number of amendments and those amendments supersede the original content.

Example 2: A user submits multiple pictures of a long receipt that should be extracted together.

How it works

Pass a package instead of a file on your request. The package.files array accepts up to 50 entries, each either a URL or an existing Extend file ID. The API ingests all files concurrently, runs extraction across the full corpus, and returns a single ExtractRun with a files array in the response (and file: null).

Quick start

from extend_ai import Extend
client = Extend()
result = client.extract_runs.create_and_poll(
    extractor={"id": "ex_abc123"},
    package={
        "files": [
            {"url": "https://example.com/invoice1.pdf"},
            {"url": "https://example.com/invoice2.pdf"},
            {"url": "https://example.com/invoice3.pdf"},
        ]
    },
)
print(result.output.value)
print("Files processed:", [f.name for f in result.files])

File inputs

Each entry in package.files can be either:

Raw text (text) and base64 inputs are not supported in multifile packages — use url or id.

You can mix URLs and file IDs in the same package:

{
  "package": {
    "files": [
      { "url": "https://example.com/cover-page.pdf" },
      { "id": "file_xK9mLPqRtN3vS8wF5hB2cQ" },
      { "url": "https://example.com/appendix.pdf" }
    ]
  }
}

Response

A multifile run returns the same ExtractRun shape as a single-file run, with two differences:

• file is null
• files is an ordered array of FileSummary objects, one per input file in submission order

{
  "object": "extract_run",
  "id": "exr_3f1j6I1gsw5k96xFiCnkM",
  "status": "PROCESSED",
  "file": null,
  "files": [
    { "object": "file", "id": "file_aaa", "name": "invoice1.pdf", ... },
    { "object": "file", "id": "file_bbb", "name": "invoice2.pdf", ... },
    { "object": "file", "id": "file_ccc", "name": "invoice3.pdf", ... }
  ],
  "output": {
    "value": { ... },
    "metadata": { ... }
  }
}

Citations and file provenance

Every citation carries a fileId telling you which input file the cited content came from. Join it against the run’s files array to attribute each extracted value to its source document — a citation’s page.number is always relative to that file, not to the corpus as a whole.

{
  "files": [
    { "object": "file", "id": "file_aaa", "name": "invoice1.pdf" },
    { "object": "file", "id": "file_bbb", "name": "invoice2.pdf" }
  ],
  "output": {
    "value": { "total_amount": 15735.1 },
    "metadata": {
      "total_amount": {
        "logprobsConfidence": 0.98,
        "citations": [
          {
            "fileId": "file_bbb",
            "page": { "number": 2, "width": 612, "height": 792 },
            "referenceText": "TOTAL  $15,735.1"
          }
        ]
      }
    }
  }
}

fileId is present whether or not bounding-box citations are enabled, so per-field provenance is available on every multifile run. See Citations for the full citation shape.

Multifile vs batch

Multifile extraction and batch processing are complementary but different:

Use multifile when your extractor schema is designed to aggregate across a set of documents. Use batch when you just want to submit many independent files efficiently.

Evaluating multifile extraction

To measure accuracy over packages, add multifile items to an evaluation set by passing fileIds (an ordered list of 2–50 file IDs) instead of fileId. Each item is evaluated as a single multifile run against one expectedOutput, and is returned with the same file: null / files: [...] shape as a multifile ExtractRun. See Add a multifile item.