Extract Archive File

transform.archive-extract pulls exactly one archive-relative path out of a ZIP and stores the bytes as a run output file. Downstream file steps consume the whole step output — {{ steps.extract.output }} — not a nested fileId field. ZIP is the only accepted archive format in this version. A nested ZIP is stored as application/zip and can be passed into List Archive or another extract step. It is not unpacked automatically. Pair this step with list + foreach (or parallel_map) when you need every matching file:

inputs:
  - name: bundle
    type: file

steps:
  - name: list
    type: transform.archive-list
    with:
      archive: "{{ input.bundle }}"

  - name: each
    type: control.foreach
    items: "{{ steps.list.output.entries }}"
    as: item
    steps:
      - name: extract
        type: transform.archive-extract
        with:
          archive: "{{ input.bundle }}"
          path: "{{ item.path }}"
      - name: parse
        type: ai.parse
        with:
          input: "{{ steps.extract.output }}"

Inside the loop, {{ steps.extract.output }} is the file from this iteration. After the loop finishes, the foreach output is an array of results — it is not itself a file handle. A nested ZIP stays a ZIP. Extract it, then list or search the extract output:

  - name: extract_packet
    type: transform.archive-extract
    with:
      archive: "{{ input.bundle }}"
      path: nested/packet.zip
  - name: list_inner
    type: transform.archive-list
    with:
      archive: "{{ steps.extract_packet.output }}"

transform.script JSON that copies a fileId is not treated as a trusted file. Only outputs from file-producing steps (including this one) rehydrate after a run resumes. Encrypted members are rejected. A nested ZIP stays a ZIP file — pass {{ steps.extract.output }} into List Archive or Search Files. Git-backed Agents do not run this step. Hosted vs headless vs on-prem ceilings: Upload files.

Limits

Each extraction is bounded at three layers:

Per entry — 64 MiB uncompressed and 64 MiB compressed for the single path this step reads.
Per ZIP reader — 512 MiB of actual inflated bytes summed across reads on that reader instance. Archive extract opens a reader, reads one entry, and closes it.
Process-wide concurrent budget — 512 MiB of declared uncompressed size across in-flight extracts in the same worker process. Extra extracts wait until inflating ones finish. Override with ZIP_PROCESS_INFLATION_BUDGET_BYTES. This is a live memory admission cap, not a persisted per-run quota: a long run can still extract more than 512 MiB in total, just not all at once.

control.parallel_map concurrency is still capped at 50, but those workers share the process budget, so a map of 50 large files cannot inflate 50 × 64 MiB simultaneously.

Limit	Value
Archive format	ZIP only
Files extracted per step	1
Max inflated size per entry	64 MiB
Max compressed size per entry	64 MiB
Max inflated bytes per ZIP reader	512 MiB
Process-wide concurrent inflation	512 MiB declared uncompressed (configurable)
`parallel_map` max concurrency	50

Configuration

Configuration goes inside the step’s with: block.

string

required

Template expression or file reference for the ZIP archive. ZIP is the only accepted format in this version.

string

required

Archive-relative path of the single file to extract, for example {{ item.path }} from a prior archive-list step.

Output

File ID from the files table

Normalized archive-relative path that was extracted

Basename of the extracted file

Detected MIME type of the extracted file

Uncompressed size in bytes

Get started

Concepts

Workflow steps

Guides & tutorials

Changelog

Limits

Configuration

Output

​Limits

​Configuration

​Output

Limits

Configuration

Output