How to download files from any website with Gaffa
Discover how Gaffa's download_file action automates file downloads at scale. Handle both auto-download and browser-rendered files with a single API call—no proxy setup, no browser management required.
Jul 21, 2026
Downloading files from the web sounds simple until you try to do it at scale. You need a headless browser, proxy management, code to detect whether a file opens inline or triggers an automatic download, retry logic, and storage handling before you have written a single line of business logic. Gaffa's download_file action collapses all of that into a single API call. This guide covers three real-world download scenarios, how to handle each one, and how Gaffa compares to doing the same thing with a traditional tool like Playwright.
What is Gaffa's download_file action?
The download_file action tells Gaffa's browser to capture the most recently loaded file and return a link to it. It automatically handles both common download patterns: files that trigger an immediate download to disk, and files that open inline in the browser, such as a PDF rendered directly in a tab. Supported formats include .pdf, .jpg, .png, .gif, .bmp, .webp, .svg, .tiff, .tif, and .img. The maximum file size is 50MB.
Because Gaffa runs a real browser behind the scenes, it handles JavaScript rendering, cookie consent, and anti-bot measures without any additional configuration. You can also set proxy_location at the request level to download files as if browsing from a specific country, which is useful for region-locked content.
Scenario 1: Downloading files — both direct and browser-rendered
Whether the file downloads automatically to disk or opens inline in the browser, the download_file action handles both patterns seamlessly without additional configuration.
Direct File Download (downloads to disk)
Browser-Rendered File (opens inline)
The optional timeout parameter sets how long Gaffa waits for the download to complete, in milliseconds. The default is 5,000ms (5 seconds); for larger files, you will want to increase this.
Gaffa returns the downloaded file as a hosted URL in the action output:
Download Action Response
You can then fetch that URL, store it, or pipe it into another workflow.
Scenario 2: Submitting a form and downloading the result
Many workflows involve generating a file in response to a form submission, a report, a certificate, or an invoice. Gaffa handles the entire sequence in a single request: fill the form, click submit, download the resulting file.
Form Submission With PDF Download
The click action submits the form by targeting the submit button via its CSS selector. Once the form is processed and the PDF is generated, download_file captures it. No polling, no callback handling, no separate request to retrieve the result. See the full Python example on GitHub.
How does this compare to doing it with Playwright?
Even for the simplest download scenario, the equivalent Playwright code requires launching a browser, configuring a context, listening for download events, waiting for the file to save, and handling storage before you have touched any proxy or retry logic. It will look something like this:
Playwright File Download (Python)
Adding a proxy to this requires passing proxy configuration into browser.new_context(). Parallelising downloads means managing multiple browser instances and their memory overhead.
With Gaffa, proxy support is a single top-level parameter (proxy_location), parallel downloads are handled by running concurrent API requests, and both inline and auto-download patterns use the same download_file interface.
Downloading files at scale
Gaffa is designed to handle volume. Higher-tier plans support multiple concurrent requests, so if you need to download hundreds of files, you can parallelise those requests across Gaffa's infrastructure rather than managing browser instances yourself.
If you're looking to download assets at scale, such as every image on a website, check out our guide on automatically scraping every image from a website. It walks through a practical approach for discovering and downloading large collections of files.
For other file types and more advanced extraction use cases, the parse_json action lets you extract structured data from any page rather than downloading the raw file. See our post on turning web content into structured data with parse_json for a detailed walkthrough.
Gaffa's download_file action removes the infrastructure overhead that makes file download automation painful at scale: no browser setup, no proxy configuration, no retry logic, no separate handling for inline versus auto-download files. Try the scenarios above directly in the API playground, or sign up for a free Gaffa account to start building.
Frequently asked questions
What file types does download_file support?
The action supports .pdf, .jpg, .png, .gif, .bmp, .webp, .svg, .tiff, .tif, and .img. The maximum file size is 50MB.
Does it matter if the file downloads automatically or opens in the browser?
No. The download_file action automatically handles both patterns without requiring additional configuration or wait actions.
How do I download files from a specific country or region?
Set proxy_location at the top level of your request to route the browser to a specific geographic location, useful for region-locked content or testing regional behaviour.
Can I run multiple downloads at the same time?
Yes. Gaffa supports concurrent download requests, with the number of simultaneous jobs depending on your plan.
Is there a file size limit?
Yes, the current maximum is 50MB per file. Contact support to discuss higher limits for your use case.
What happens if a download fails?
Gaffa handles failures gracefully and returns an error response detailing what went wrong.
