Downloads

Hyperbrowser makes it easy to download files during your browser sessions. The files you download get stored securely in our cloud infrastructure as a zip file. You can then retrieve them using a simple API call.

How to Download Files:

  1. Create a new Hyperbrowser session and set the saveDownloads param to true

  2. Connect to the session using your preferred automation framework (like Puppeteer or Playwright)

  3. Set the download location in your code

  4. Download files

  5. Retrieve the download zip URL from Sessions API

Retrieving Downloads

  1. Note the id of the session you want to retrieve downloads for

  2. Use the Sessions Downloads API to get the downloadsUrl for the zip, or if you are using the SDKs, you can just call the getDownloadsURL function

The response for the getDownloadsURL will have a status associated with it which can be not_enabled if saveDownloads was not enabled for the session, pending or in_progress if the zip file is in progress of being uploaded to our storage, and completed or failed once it is finished.

status: "not_enabled" | "pending" | "in_progress" | "completed" | "failed"
downloadsUrl: string | null
error?: string | null
import { connect } from "puppeteer-core";
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const hbClient = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const main = async () => {
  const session = await hbClient.sessions.create({
    saveDownloads: true,
  });

  try {
    const browser = await connect({
      browserWSEndpoint: session.wsEndpoint,
    });
    const page = (await browser.pages())[0];

    const cdp = await browser.target().createCDPSession();
    await cdp.send("Browser.setDownloadBehavior", {
      behavior: "allow",
      downloadPath: "/tmp/downloads",
      eventsEnabled: true,
    });

    await page.goto("https://browser-tests-alpha.vercel.app/api/download-test");

    // Download file from the page
    // Set up download listener
    cdp.on("Browser.downloadWillBegin", (event) => {
      console.log("Download started:", event.suggestedFilename);
    });

    // Create a promise that resolves when the download is complete
    const downloadPromise = new Promise((resolve) => {
      cdp.on("Browser.downloadProgress", (event) => {
        if (event.state === "completed" || event.state === "canceled") {
          resolve("Done");
        }
      });
    });

    // Start the download and wait for it to complete
    await Promise.all([downloadPromise, page.locator("#download").click()]);

    console.log("Download completed");

    await hbClient.sessions.stop(session.id);

    await sleep(3000);

    // Wait for the zipped downloads to be uploaded to our storage
    let downloadsResponse = await hbClient.sessions.getDownloadsURL(session.id);
    while (downloadsResponse.status === "in_progress") {
      console.log("Waiting for downloads zip to be ready...");
      await sleep(1000);
      downloadsResponse = await hbClient.sessions.getDownloadsURL(session.id);
    }

    console.log("downloadsResponse", downloadsResponse);
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await hbClient.sessions.stop(session.id);
  }
};

main().catch((err) => console.error(`Encountered error: ${err}`));

Using With AI Agents

Similarly as above, you can get the downloads zip of files that were downloaded during the session used by an AI Agent. We just need to create a session with saveDownloads set to True and then pass in that session ID. Here is an example of doing it with OpenAI CUA.

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const hbClient = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const main = async () => {
  const session = await hbClient.sessions.create({
    saveDownloads: true,
  });

  try {
    const resp = await hbClient.agents.cua.startAndWait({
      task: "1. Go to this site https://browser-tests-alpha.vercel.app/api/download-test. 2. Click on the Download File link once, then end the task. Do not wait or double check the download, just end the task.",
      sessionId: session.id,
    });

    console.log("Status:", resp.status);
    console.log("Final result:", resp.data?.finalResult);
    await hbClient.sessions.stop(session.id);

    await sleep(3000);

    // Wait for the zipped downloads to be uploaded to our storage
    let downloadsResponse = await hbClient.sessions.getDownloadsURL(session.id);
    while (downloadsResponse.status === "in_progress") {
      console.log("Waiting for downloads zip to be ready...");
      await sleep(1000);
      downloadsResponse = await hbClient.sessions.getDownloadsURL(session.id);
    }

    console.log("downloadsResponse", downloadsResponse);
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await hbClient.sessions.stop(session.id);
  }
};

main().catch((err) => console.error(`Encountered error: ${err}`));

Storage and Retention

Download zip files are stored securely in Hyperbrowser's cloud infrastructure and are retained according to your plan's data retention policy.

Last updated