> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eigenpal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract Archive File

> Extract exactly one file from a ZIP archive and store it as a run output file. Downstream steps can pass the whole extract output into Parse, Vision, or another archive step.

`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](https://docs.eigenpal.com/steps/transform/archive-list.md)
or another extract step. It is not unpacked automatically.

Pair this step with list + foreach (or parallel\_map) when you need every
matching file:

```yaml theme={null}
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-v2
        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:

```yaml theme={null}
  - 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](https://docs.eigenpal.com/steps/transform/archive-list.md)
or [Search Files](https://docs.eigenpal.com/steps/ai/search-files.md). Git-backed Agents do not run this
step. Hosted vs headless vs on-prem ceilings: [Upload files](https://docs.eigenpal.com/guides/upload-files.md).

## Limits

Each extraction is bounded at three layers:

1. **Per entry** — 64 MiB uncompressed and 64 MiB compressed for the single
   path this step reads.
2. **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.
3. **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.

**archive** `string` *required*

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

**path** `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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.