Overview

Learn about Hyperbrowser Sessions

In Hyperbrowser, a Session is simply a dedicated, cloud-based browser instance that’s yours to direct. It’s like opening a fresh, private browser window—only this one lives in the cloud and is fully controllable through code. Each Session keeps its own cookies, storage, and browsing context, so you can run your tasks without mixing them up.

With our Sessions API, you can spin up these browser environments whenever you need them, configure them with optional parameters, and close them down when you’re done. Higher level endpoints like scrape and crawl also utilize sessions internally to handle their tasks.

Connect with your favorite browser automation libraries

Puppeteer

Connect with Puppeteer to automate browser actions via a websocket connection

Playwright

Connect with Playwright to automate browser actions via a websocket connection

Check out our API Reference to see the Sessions API in more detail

Usage

Starting a session is pretty simple, you can either startup a session directly by connecting to our websocket endpoint with your preferred automation tool like Playwright or Puppeteer, or you can create a session via the Sessions API.

Simple Connect

With this approach, you can startup a session with all default configurations set by just changing one line.

Node

Puppeteer

const browser = await puppeteer.connect({
    browserWSEndpoint: `wss://connect.hyperbrowser.ai?apiKey=${process.env.HYPERBROWSER_API_KEY}`,
});

Playwright

const browser = await chromium.connectOverCDP(
    `wss://connect.hyperbrowser.ai?apiKey=${process.env.HYPERBROWSER_API_KEY}`
);

Python

Puppeteer

browser = await pyppeteer.connect(
    browserWSEndpoint=f"wss://connect.hyperbrowser.ai?apiKey={os.getenv('HYPERBROWSER_API_KEY')}"
)

Playwright

with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(
            f"wss://connect.hyperbrowser.ai?apiKey={os.getenv('HYPERBROWSER_API_KEY')}"
        )

The simple connect approach doesn't support setting parameters. Use the Session API below for customizing session parameters, such as proxies, web recordings, or extensions.

Connect with Sessions API

With this approach, you have more control over your sessions with additional features or updated configurations.

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({
    useStealth: true,
  });

  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({
    useStealth: true,
  });

  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_stealth=True,
        )
    )

    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

# You can also use the sync `Hyperbrowser` to work with sync_playwright
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 Playwright
    session = await client.sessions.create(
        params=CreateSessionParams(
            use_stealth=True,
        )
    )

    # Initialize Playwright and connect to the browser
    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())

Hyperbrowser's CAPTCHA solving and Proxy features require being on a PAID plan.