Proxies

Route browser traffic through proxies to change IP addresses. You can:

• Use Hyperbrowser's proxy pool

• Bring your own proxies

To enable these proxy configurations, you can set them in the session creation params.

Node

Puppeteer

import { connect } from "puppeteer-core";
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

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

const main = async () => {
  const session = await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
    // use own proxy
    /**
     * proxyServer: "http://...",
     * proxyServerUsername: "...",
     * proxyServerPassword: "...",
     */
  });

  try {
    const browser = await connect({
      browserWSEndpoint: session.wsEndpoint,
      defaultViewport: null,
    });

    const [page] = await browser.pages();

    // Navigate to a website
    console.log("Navigating to Hacker News...");
    await page.goto("https://news.ycombinator.com/");
    const pageTitle = await page.title();
    console.log("Page 1:", pageTitle);
    await page.evaluate(() => {
      console.log("Page 1:", document.title);
    });
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
};

main();

Playwright

import { chromium } from "playwright-core";
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

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

const main = async () => {
  const session = await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
    // use own proxy
    /**
     * proxyServer: "http://...",
     * proxyServerUsername: "...",
     * proxyServerPassword: "...",
     */
  });

  try {
    const browser = await chromium.connectOverCDP(session.wsEndpoint);

    const context = browser.contexts()[0];
    const page = await context.newPage();

    // Navigate to a website
    console.log("Navigating to Hacker News...");
    await page.goto("https://news.ycombinator.com/");
    const pageTitle = await page.title();
    console.log("Page 1:", pageTitle);
    await page.evaluate(() => {
      console.log("Page 1:", document.title);
    });
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
};

main();

Python

Puppeteer

import asyncio
from pyppeteer import connect
import os
from dotenv import load_dotenv
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import CreateSessionParams

# Load environment variables from .env file
load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    # Create a session and connect to it using Pyppeteer
    session = await client.sessions.create(
        params=CreateSessionParams(
            use_proxy=True,
            proxy_country="US",
            # use own proxy
            # proxy_server="http://...",
            # proxy_server_username="...",
            # proxy_server_password="...",
        )
    )

    try:
        browser = await connect(
            browserWSEndpoint=session.ws_endpoint, defaultViewport=None
        )

        pages = await browser.pages()
        page = pages[0]

        # Navigate to a website
        print("Navigating to Hacker News...")
        await page.goto("https://news.ycombinator.com/")
        page_title = await page.title()
        print("Page title:", page_title)
        await page.evaluate("() => { console.log('Page 1:', document.title); }")

    except Exception as e:
        print(f"Error: {e}")
    finally:
        await client.sessions.stop(session.id)


# Run the async main function
if __name__ == "__main__":
    asyncio.run(main())

Playwright

import asyncio
from playwright.async_api import async_playwright
import os
from dotenv import load_dotenv
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import CreateSessionParams

# Load environment variables from .env file
load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    # Create a session and connect to it using Pyppeteer
    session = await client.sessions.create(
        params=CreateSessionParams(
            use_proxy=True,
            proxy_country="US",
            # use own proxy
            # proxy_server="http://...",
            # proxy_server_username="...",
            # proxy_server_password="...",
        )
    )

    try:
        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(session.ws_endpoint)
            default_context = browser.contexts[0]
            page = await default_context.new_page()

            # Navigate to a website
            print("Navigating to Hacker News...")
            await page.goto("https://news.ycombinator.com/")
            page_title = await page.title()
            print("Page title:", page_title)
            await page.evaluate("() => { console.log('Page 1:', document.title); }")

    except Exception as e:
        print(f"Error: {e}")
    finally:
        await client.sessions.stop(session.id)


# Run the async main function
if __name__ == "__main__":
    asyncio.run(main())

Using proxies can introduce latency to any page navigations, so make sure to properly await these navigations with timeouts.

Proxy usage requires being on a PAID plan.

Geospecific Proxies

Hyperbrowser supports geo-specific IPs as well. The specificity can range from country level down to city level. This can be specified by

Node

...
await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
    // or proxyCity: "New York"
  });
...

Python

...
await client.sessions.create(
    params=CreateSessionParams(
        use_proxy=True,
        proxy_country="US",
        # or proxy_city="New York"
    )
)
...

While Hyperbrowser supports nearly all countries and most cities, not all areas are guaranteed to be available. Especially for areas with low population density, separate testing should be done to ensure that adequate coverage is available.

Custom Proxies

If you want to use your own proxy service/providers, you can do so by specifying the following parameters when creating a session. If you use your own proxy provider, you will not be billed for any proxy usage.

When setting the proxyServer, ensure that you start it with the scheme like http:// for example.

Node

...
await client.sessions.create({
    useProxy: true,
    proxyServer: "scheme://subdomain.proxyprovider.io:10000",
    proxyServerUsername: "proxy-username",
    proxyServerPassword: "proxy-password",
  });
...

Python

...
await client.sessions.create(
    params=CreateSessionParams(
        use_proxy=True,
        proxy_server="scheme://subdomain.proxyprovider.io:10000",
        proxy_server_username="proxy-username",
        proxy_server_password="proxy-password",
    )
)
...

Proxy usage is only available on the PAID plans.