# Bulk File Downloader: URL List to Storage & ZIP (`ucchiii/bulk-file-downloader`) Actor

Download files from a list of URLs or a dataset field into Apify storage: one row per file with a download link, content type, size and SHA-256, plus an optional ZIP of everything. Filter by extension or type, set size limits. Failed downloads are free. Empty input = free demo.

- **URL**: https://apify.com/ucchiii/bulk-file-downloader.md
- **Developed by:** [Actor Factory](https://apify.com/ucchiii) (community)
- **Categories:** Developer tools, Automation, Integrations
- **Features:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.91 / 1,000 saved files

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

**Bulk file downloader: give it a list of file URLs (or point it at a field of another Actor's dataset) and every file is saved to Apify storage, with one row per file — a direct download link, content type, size, SHA-256 checksum and status. Optionally, everything is packed into one ZIP.**

| url | status | fileName | contentType | bytes | publicUrl |
|---|---|---|---|---|---|
| https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf | stored | dummy.pdf | application/pdf | 13264 | https://api.apify.com/v2/key-value-stores/…/records/00001-dummy.pdf |
| https://www.python.org/static/img/python-logo.png | stored | python-logo.png | image/png | 15770 | https://api.apify.com/v2/key-value-stores/…/records/00002-python-logo.png |
| https://apify.com/robots.txt | stored | robots.txt | text/plain | 203 | https://api.apify.com/v2/key-value-stores/…/records/00003-robots.txt |
| https://apify.com/this-file-does-not-exist-9f3k2.pdf | error | | | | |

*(real rows from a run on Apify on 2026-11-12: 3 files saved = 3 `file` events plus 1 `data-10mb` event for 29,237 bytes; the missing file is an error row and is free)*

**For anyone who has a list of links and needs the files themselves:** archive PDFs, invoices or reports, collect product
images that a scraper found, back up CSV or JSON exports, pull attachments into an AI or RAG pipeline, or hand a colleague one
ZIP instead of 300 links.

**Try it:** press **Start** with the prefilled example (3 small public files). You get 3 rows and 3 saved files in a few
seconds, for well under 1 cent. Clear the URL list and press Start for a **free demo** (3 files and a ZIP; rows carry
`_demo: true`, not charged).

### What you get

- **Every file saved to the run's key-value store**, under a readable key such as `00001-q3-report.pdf` (input position + file
  name, so two files called `image.jpg` never overwrite each other), with the server's content type.
- **One row per URL**: `url`, `status`, `fileName`, `key`, `publicUrl` (direct download link), `contentType`, `bytes`, `sha256`,
  `inZip`, `finalUrl`, `httpStatus`, `redirects`, `error`, `downloadedAt`. Export it as CSV, JSON or Excel, or read it with the API.
- **Optional ZIP** (`Create ZIP`): all saved files in one `files.zip`, with a link in the run's output tab and in the SUMMARY
  record. Duplicate names get `-2`, `-3`. Images, PDFs and archives are stored as they are (no slow recompression); text files are compressed.
- **Safe file names**: the name comes from the server's `Content-Disposition` header or the URL path. Folder parts (`../`) are
  removed, accents are turned into plain letters, anything other than letters, digits and `. _ - ( ) ' !` becomes `_`, reserved
  Windows names are replaced, long names are shortened (the extension is kept), and a missing extension is added from the content type.
- **SHA-256 checksum** of each file, to spot duplicates or check integrity later.
- **Filters**: keep only some extensions (`pdf`, `jpg`…) or content types (`image/*`, `application/pdf`). Handy when some links
  return an HTML error page instead of the file: `allowedContentTypes: ["application/pdf"]` turns those into free `filtered_out` rows.
- **Limits you control**: max size per file, max total size per run, max size of the ZIP.
- **URLs from a dataset**: pick the dataset of a scraper run and name the field (`url`, `imageUrl`, `product.images`…). If the
  field holds a list of URLs, every one of them is downloaded.

### How to use

1. **File URLs**: one direct link per line (up to 5,000 per run; duplicates are removed). Or choose a **Dataset with URLs**
   and set **URL field in dataset**.
2. Optional: **Create ZIP**, **Allowed extensions**, **Allowed content types**, **Max file size**, **Total size limit**,
   **Concurrency**, **Max connections per host**, **Delay per host**, **Timeout**, **Max redirects**, **Retries**, **User-Agent**.
3. Press **Start**. Open the **Output** tab for the table and the ZIP link.

```json
{
  "urls": ["https://example.com/a.pdf", "https://example.com/b.pdf"],
  "allowedContentTypes": ["application/pdf"],
  "maxFileSizeMb": 50,
  "createZip": true
}
```

From another Actor's results (for example a product scraper with an `images` list on each item):

```json
{ "datasetId": "<defaultDatasetId of that run>", "urlField": "images", "allowedContentTypes": ["image/*"] }
```

### Output

```json
{
  "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "status": "stored",
  "fileName": "dummy.pdf",
  "key": "00001-dummy.pdf",
  "publicUrl": "https://api.apify.com/v2/key-value-stores/<store>/records/00001-dummy.pdf?signature=…",
  "contentType": "application/pdf",
  "bytes": 13264,
  "sha256": "3df79d34abbca99308e79cb94461c1893582604d68329a41fd4bec1885e6adb4",
  "inZip": true,
  "finalUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "httpStatus": 200,
  "redirects": 0,
  "error": null,
  "downloadedAt": "2026-11-12T09:36:57+00:00"
}
```

*(real row from a run on Apify on 2026-11-12)*

- `status` — `stored` (downloaded and saved; charged), `error`, `filtered_out` (extension or content type not allowed),
  `too_large` (over **Max file size**), `skipped_total_limit` (the run reached **Total size limit**) or `invalid_input`. Only `stored` is charged.
- `error` — e.g. `http_404`, `http_403`, `timeout`, `dns_failure`, `blocked_private_address`, `too_many_redirects`,
  `redirect_loop`, `invalid_redirect_url`, `file_too_large`, `total_limit_reached`, `extension_not_allowed: html`,
  `content_type_not_allowed: text/html`, `empty_body`; `invalid_url` for input that is not an http(s) URL.
- `inZip` — `true` / `false` (left out because the ZIP size limit was reached; the file itself is still saved), `null` when no ZIP was made.
- **SUMMARY** record: URLs processed, `stored`, `errors`, `filteredOut`, `tooLarge`, `skippedTotalLimit`, `invalidInput`,
  `storedBytes`, `chargedFiles`, `chargedDataUnits`, `zipUrl`, `zipBytes`, `zipFiles`, `zipSkippedFiles`, `stoppedByChargeLimit`.

### Pricing

Pay per event, two parts:

| Event | Price | When |
|---|---|---|
| Saved file (`file`) | $0.0013 per file ($1.30 per 1,000) | each file downloaded and saved |
| Saved 10 MB block (`data-10mb`) | $0.0005 per block | each started 10 MB of saved data in the run |

**How the 10 MB blocks are counted:** all files saved in one run are added up (1 MB = 1,000,000 bytes) and the total is divided
by 10,000,000 and **rounded up**, once for the whole run — not per file. Examples: 300 images totalling 2.4 MB → 1 block;
3 files of 4 MB (12 MB) → 2 blocks; 1,000 PDFs totalling 850 MB → 85 blocks. The ZIP is a copy and is not counted.

| Example run | Files | Data | Total |
|---|---|---|---|
| 1,000 product images, 150 KB each (150 MB) | $1.30 | 15 × $0.0005 = $0.0075 | $1.3075 |
| 100 PDFs, 2 MB each (200 MB) | $0.13 | 20 × $0.0005 = $0.01 | $0.14 |
| 10 videos, 80 MB each (800 MB) | $0.013 | 80 × $0.0005 = $0.04 | $0.053 |

**Not charged:** failed downloads (404, timeouts, blocked addresses, empty responses), files removed by your filters, files over
your size limits, URLs skipped after the total limit, invalid URLs, retries, the ZIP, and the free demo (empty input).
Set a **maximum charge per run** to cap spend: the run stops cleanly when it is reached, and files downloaded after that point are not kept.
Storage of the saved files follows your Apify plan's normal data retention.

### Notes and limits

- **Plain HTTP, no browser, no crawling.** Only the URLs you give are requested. Links that need a login, a cookie, or a page
  that runs JavaScript before the download starts will fail or return an HTML page (use **Allowed content types** to skip those).
- **Polite by default**: at most 2 connections per host and at least 0.5 s between requests to the same host (adjustable,
  never below 0.1 s), up to 5 redirects, timeouts on every request, up to 2 retries for temporary errors (429, 5xx, timeouts).
- **Safe by design**: addresses that resolve to internal networks (localhost, private ranges, link-local such as
  169.254.169.254, IPv6 loopback/unique-local) are never contacted. Redirects are followed one hop at a time and each hop is
  checked the same way — reported as `blocked_private_address`.
- **Size**: up to 500 MB per file and 500 MB per ZIP. Big files are held in memory while they are saved; with the default 1 GB of
  memory, files up to about 100 MB at the default concurrency should fit (estimate, not yet measured on large files). For larger files or ZIPs, raise the run's memory.
- When the total size limit is reached, no further files are requested.
- **Only download files you have the right to copy and store.** The files belong to their owners; this Actor does not check
  licences or copyright. Respect the terms of the sites you download from.

### FAQ

**Am I charged when a link is broken?** No. Only files that were really downloaded and saved are charged. A 404, a timeout or
an HTML error page removed by your content-type filter costs nothing.

**Why is the data charge per run and not per file?** So that many small files cost almost nothing extra: 1,000 thumbnails of
20 KB each add only 2 blocks ($0.001) on top of the per-file price.

**Can I keep the original file names?** The file name is kept as far as it is safe: `Q3 Report (final).pdf` becomes
`Q3_Report_(final).pdf`. Inside the ZIP the same safe names are used; the storage key adds a 5-digit number in front.

**How do I get all files at once?** Turn on **Create ZIP** and download `files.zip` from the Output tab, or read each `publicUrl`.

If this Actor saved you time, a rating on the Store helps others find it.

### More tools from the same developer

- [Image Converter](https://apify.com/ucchiii/image-converter) — convert images between JPG, PNG, WebP and AVIF, with optional resize
- [PDF Extractor](https://apify.com/ucchiii/pdf-extractor) — PDF to text, tables and metadata from public PDF URLs, page by page
- [Bulk URL Status Checker](https://apify.com/ucchiii/url-status-checker) — bulk HTTP status and redirect-chain checker for URL lists
- [Bulk HTTP Request](https://apify.com/ucchiii/bulk-http-request) — send many HTTP requests (GET/POST/...) from a list and collect status, headers and body
- [Tesseract OCR](https://apify.com/ucchiii/ocr-image-text) — OCR for image URLs and scanned PDFs with built-in Tesseract: text, confidence and line boxes in 8 languages

# Actor input Schema

## `urls` (type: `array`):

Direct links to the files to download, one per line, e.g. 'https://example.com/report.pdf'. Without a scheme, https:// is used. Duplicates are removed; up to 5,000 URLs per run (the rest are skipped). Leave empty (and no dataset) for a free demo (not charged).

## `datasetId` (type: `string`):

Optional. ID of a dataset (for example a finished run's 'defaultDatasetId') whose items contain file URLs, such as the output of a scraper. The URLs are added after the list above; the 5,000-URL cap applies to the total.

## `urlField` (type: `string`):

Field of each dataset item that holds the URL. Use dots for nested fields, e.g. 'product.image' or 'images.0'. The field may also hold a list of URLs (e.g. 'imageUrls'): every URL in it is downloaded. Default 'url'.

## `createZip` (type: `boolean`):

Also put all saved files into one ZIP archive (key 'files.zip' in the key-value store; its link is in the SUMMARY record and the run's output tab). Same file names get -2, -3... Images, PDFs and archives are stored without recompression. No extra charge.

## `zipMaxSizeMb` (type: `integer`):

Largest total size of the files that go into the ZIP (1 to 500 MB, default 200). Files that no longer fit are still saved one by one, only left out of the ZIP (inZip: false). For a ZIP over 200 MB, give the run 2 GB of memory or more.

## `allowedExtensions` (type: `array`):

Optional. Save only files whose name ends in one of these extensions, e.g. 'pdf', 'jpg', 'png' (without dot, case does not matter). The name comes from the server's Content-Disposition header or the URL path; when it has no extension, one is taken from the content type. Others become filtered_out rows (free). Empty = all.

## `allowedContentTypes` (type: `array`):

Optional. Save only files whose Content-Type matches, e.g. 'application/pdf' (exact) or 'image/\*' (all images). Use it to skip HTML error pages served instead of a file. Others become filtered_out rows (free). Empty = all.

## `maxFileSizeMb` (type: `integer`):

Files larger than this are not saved (status too_large, free). Checked from the Content-Length header before downloading, and again while reading. 1 to 500 MB, default 50. For files over 100 MB, raise the run's memory.

## `maxTotalSizeMb` (type: `integer`):

Stop downloading once the files saved in this run reach this total (1 to 20,000 MB, default 1,000). The remaining URLs get status skipped_total_limit and are free. Keeps the cost of a run predictable.

## `concurrency` (type: `integer`):

How many files are downloaded in parallel in total (1 to 20, default 5). Per-host limits below still apply.

## `maxConnectionsPerHost` (type: `integer`):

How many downloads may run at the same time against one host name (1 to 10, default 2). Keep it low for small websites.

## `delayPerHostSecs` (type: `number`):

Minimum time between the start of two requests to the same host (0.1 to 30 seconds, default 0.5). Requests to different hosts are not delayed.

## `timeoutSecs` (type: `integer`):

Timeout for connecting and for each read while downloading, in seconds (1 to 300, default 60). A large file may take longer in total as long as data keeps coming.

## `maxRedirects` (type: `integer`):

How many redirects are followed per file (0 to 10, default 5). Every hop is checked: redirects to internal network addresses are refused.

## `retries` (type: `integer`):

How many times a download is retried after a timeout, a connection error or HTTP 429/500/502/503/504 (0 to 5, default 2), with a short wait in between. Retries are not charged.

## `userAgent` (type: `string`):

Optional custom User-Agent header. By default the requests identify this Actor.

## Actor input object example

```json
{
  "urls": [
    "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "https://www.python.org/static/img/python-logo.png",
    "https://apify.com/robots.txt"
  ],
  "urlField": "url",
  "createZip": false,
  "zipMaxSizeMb": 200,
  "allowedExtensions": [
    "pdf",
    "jpg",
    "png"
  ],
  "allowedContentTypes": [
    "image/*",
    "application/pdf"
  ],
  "maxFileSizeMb": 50,
  "maxTotalSizeMb": 1000,
  "concurrency": 5,
  "maxConnectionsPerHost": 2,
  "delayPerHostSecs": 0.5,
  "timeoutSecs": 60,
  "maxRedirects": 5,
  "retries": 2,
  "userAgent": "Mozilla/5.0 (compatible; my-archiver/1.0)"
}
```

# Actor output Schema

## `files` (type: `string`):

One row per URL: status, fileName, publicUrl (link to the saved file), contentType, bytes, sha256, inZip, key, finalUrl, httpStatus, redirects, error.

## `zip` (type: `string`):

files.zip with every saved file (only when 'Create ZIP' is on and at least one file was saved).

## `summary` (type: `string`):

Record SUMMARY: URLs processed, files stored, errors, filtered out, too large, skipped by the total limit, invalid input, stored bytes, charged files and 10 MB units, ZIP link and size, and whether the run stopped at the maximum charge.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
        "https://www.python.org/static/img/python-logo.png",
        "https://apify.com/robots.txt"
    ],
    "urlField": "url",
    "zipMaxSizeMb": 200,
    "maxFileSizeMb": 50,
    "maxTotalSizeMb": 1000,
    "concurrency": 5,
    "maxConnectionsPerHost": 2,
    "delayPerHostSecs": 0.5,
    "timeoutSecs": 60,
    "maxRedirects": 5,
    "retries": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("ucchiii/bulk-file-downloader").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "urls": [
        "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
        "https://www.python.org/static/img/python-logo.png",
        "https://apify.com/robots.txt",
    ],
    "urlField": "url",
    "zipMaxSizeMb": 200,
    "maxFileSizeMb": 50,
    "maxTotalSizeMb": 1000,
    "concurrency": 5,
    "maxConnectionsPerHost": 2,
    "delayPerHostSecs": 0.5,
    "timeoutSecs": 60,
    "maxRedirects": 5,
    "retries": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("ucchiii/bulk-file-downloader").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "https://www.python.org/static/img/python-logo.png",
    "https://apify.com/robots.txt"
  ],
  "urlField": "url",
  "zipMaxSizeMb": 200,
  "maxFileSizeMb": 50,
  "maxTotalSizeMb": 1000,
  "concurrency": 5,
  "maxConnectionsPerHost": 2,
  "delayPerHostSecs": 0.5,
  "timeoutSecs": 60,
  "maxRedirects": 5,
  "retries": 2
}' |
apify call ucchiii/bulk-file-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ucchiii/bulk-file-downloader"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gM8zA3ZiSs2xmMUlK/builds/Hih8dA3nwLqzzpdAf/openapi.json
