Multifile Extraction in Workflows

Multifile extraction is not limited to standalone /extract_runs calls. A workflow can accept a package of files and run one extraction across all of them, with validation, review, and routing applied to the combined result.

For the core concept, the package parameter, and the response shape, start with Multifile Extraction. This page covers what changes when you run it inside a workflow.

How it works

A standard workflow run takes one file and processes it end to end. A package run takes 2 to 50 files and processes them as a single unit, producing one workflow run.

Inside that run, a Collect step gathers all the files, and any Extract step placed downstream of Collect performs a multifile extraction: one extraction, one output object, shared context across every file in the package.

1. You submit a package of 2 to 50 files against a workflow.
2. Extend creates one workflow run containing every file.
3. The Trigger and Parse steps run once per file. Each file is parsed independently.
4. The Collect step waits for every file to finish upstream processing, then accumulates them into a single step run.
5. Every step downstream of Collect runs in multi-file mode. An Extract step there receives all collected files at once and performs a single multifile extraction.
6. Downstream Validation, Router, Human Review, and Webhook Response steps operate on that one combined result.

                ┌─ Parse (file 1) ─┐
Trigger (×N) ───┼─ Parse (file 2) ─┼─→ Collect ─→ Extract ─→ Webhook
                └─ Parse (file 3) ─┘             (multifile)

Configure the workflow

Add a COLLECT step between your parse step and the extract step.

Quick start

1
from extend_ai import Extend
2
3
client = Extend()
4
5
workflow = client.workflows.create(
6
    name="Package extraction workflow",
7
    steps=[
8
        {"type": "TRIGGER", "name": "trigger", "next": [{"step": "parse"}]},
9
        {"type": "PARSE", "name": "parse", "next": [{"step": "collect"}]},
10
        {"type": "COLLECT", "name": "collect", "next": [{"step": "extract_package"}]},
11
        {
12
            "type": "EXTRACT",
13
            "name": "extract_package",
14
            "config": {"extractor": {"id": "ex_abc123", "version": "latest"}},
15
            "next": [{"step": "respond"}],
16
        },
17
        {"type": "WEBHOOK_RESPONSE", "name": "respond"},
18
    ],
19
)
20
21
print("Workflow:", workflow.id)

Steps accumulate on the workflow’s draft. Deploy a version before running it. See Workflow Versioning.

Start a package run

Use package instead of file on POST /workflow_runs. The two are mutually exclusive. You can mix file URLs and file IDs in the same package.

1
from extend_ai import Extend
2
3
client = Extend()
4
5
# For most production use cases, we recommend webhooks instead of polling
6
result = client.workflow_runs.create_and_poll(
7
    workflow={"id": "workflow_abc123", "version": "latest"},
8
    package={
9
        "files": [
10
            {"url": "https://example.com/msa.pdf"},
11
            {"url": "https://example.com/amendment-1.pdf"},
12
            {"id": "file_xK9mLPqRtN3vS8wF5hB2cQ"},
13
        ]
14
    },
15
)
16
17
print("Workflow run:", result.status)

For the full list of package constraints (file count, accepted input shapes, duplicates, and outputs), see Package runs.

Response

A package run returns a single workflow_run object. Workflow runs always expose a files array, so the response shape does not change between single-file and package runs. For a package run, that array holds every file you submitted, in submission order.

Inside the run:

• The Parse step has one step run per file.
• The Extract step has a single step run whose extraction run covers the whole corpus. Its file is null and its files array lists every input file in order.
• output.value is one object for the entire package.
• Citations carry a fileId so you can trace each extracted value back to the source document. See Citations and file provenance for the field shape.

In the dashboard, the workflow run review screen shows a tab per step. The extraction tab shows the single combined output with per-file citations.

Comparison

Use a package run when the answer spans documents. Use batch runs when the documents are independent and you want a result per file.

Next steps