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

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

Python

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

Connect with Sessions API

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

Node

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({
    solveCaptchas: true,
    useStealth: true,
    useProxy: true,
  });
  const browser = await connect({
    browserWSEndpoint: session.wsEndpoint,
  });

  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);
  });

  // Clean up
  await page.close();
  await browser.close();
  await client.sessions.stop(session.id);
};

main();

Python

import asyncio
from pyppeteer import connect
import os
from dotenv import load_dotenv
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models.session 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(
            solve_captchas=True, use_stealth=True, use_proxy=True
        )
    )
    browser = connect(browserWSEndpoint=session.ws_endpoint)

    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); }")

    # Clean up
    await page.close()
    await browser.close()
    await client.sessions.stop(session.id)

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