Configuring Sessions

Sessions are isolated browser instances running in the cloud that you can control programmatically. Each session gives you a WebSocket endpoint to connect with Playwright, Puppeteer, or any CDP-compatible tool. To purchase a session with a wallet instead of an API key, see Sessions with X402.

Quick Start

Create a session with default settings:

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

config();

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

async function main() {
  const session = await client.sessions.create();

  console.log("Session ID:", session.id);
  console.log("WebSocket:", session.wsEndpoint);
  console.log("Live Url:", session.liveUrl);
}

main();

from hyperbrowser import Hyperbrowser
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

session = client.sessions.create()

print(f"Session ID: {session.id}")
print(f"WebSocket: {session.ws_endpoint}")
print(f"Live Url: {session.live_url}")

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

You can view the live session at the live url link provided in the response. Active sessions can be also viewed and managed in the Sessions page in the dashboard.

Remember to stop the sessions when are you are done with them. See the Session Lifecycle guide for more information on managing sessions through code.

Configuration Options

Customize your session with these options:

const session = await client.sessions.create({
  acceptCookies: true,
  useStealth: true,
  useUltraStealth: false,
  useProxy: true,
  screen: {
    width: 1920,
    height: 1080,
  },
  timeoutMinutes: 30,
});

session = client.sessions.create(
    {
        "accept_cookies": True,
        "use_stealth": True,
        "use_ultra_stealth": False,
        "use_proxy": True,
        "screen": {"width": 1920, "height": 1080},
        "timeout_minutes": 30,
    }
)

from hyperbrowser.models import CreateSessionParams, ScreenConfig

session = client.sessions.create(
    params=CreateSessionParams(
        accept_cookies=True,
        use_stealth=True,
        use_ultra_stealth=False,
        use_proxy=True,
        screen=ScreenConfig(width=1920, height=1080),
        timeout_minutes=30,
    )
)

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "acceptCookies": true,
    "useStealth": true,
    "useUltraStealth": false,
    "useProxy": true,
    "screen": {
      "width": 1920,
      "height": 1080
    },
    "timeoutMinutes": 30
  }'

Common Configuration Options

boolean

default:false

Automatically accept cookies on pages that are visited in the session

boolean

default:false

Enable standard stealth mode to evade basic bot detection

boolean

default:false

Enable advanced stealth mode for maximum bot detection evasion (reach out to us at info@hyperbrowser.ai to get access)

boolean

default:false

Route traffic through a proxy (see Proxy Guide for configuration)

object

Screen dimensions with width and height (default: 1280x720)

number

Session timeout in minutes (min: 1, max: 720)

This shows the most commonly used options. For the complete list of configuration parameters including proxy settings, CAPTCHA solving, recordings, profiles, extensions, and more, see:

Session Parameters - Full parameter reference
Python SDK Documentation - Python SDK session creation and typing
Node.js SDK Documentation - Node.js SDK guide and typing
API Reference - Complete REST API documentation

Session Response

The API returns a session object with these properties:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "sessionUrl": "https://...",
  "wsEndpoint": "wss://...",
  "liveUrl": "https://...",
  "computerActionEndpoint": "https://...",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z"
}

To see the complete list of properties, see the API Reference.

string

Unique session identifier

string

WebSocket URL for browser automation

string

URL to view the session in real-time

string

URL to view the session page in the dashboard

string

URL to send computer actions to the session

string

Current status (active, closed, or error)

string

ISO 8601 timestamp

object | null

The parameters that were used to launch the session. See the API Reference for more details.

number | null

Credits used by the session

Stealth Mode

Bypass bot detection with stealth features:

// Standard stealth (recommended for most sites)
const session = await client.sessions.create({
  useStealth: true,
});

// Ultra stealth (for challenging sites)
const session = await client.sessions.create({
  useUltraStealth: true,
});

# Standard stealth (recommended for most sites)
session = client.sessions.create(params={"use_stealth": True})

# Ultra stealth (for challenging sites)
session = client.sessions.create(params={"use_ultra_stealth": True})

from hyperbrowser.models import CreateSessionParams

# Standard stealth (recommended for most sites)
session = client.sessions.create(params=CreateSessionParams(use_stealth=True))

# Ultra stealth (for challenging sites)
session = client.sessions.create(params=CreateSessionParams(use_ultra_stealth=True))

# Standard stealth
curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"useStealth": true}'

# Ultra stealth
curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"useUltraStealth": true}'

Ultra stealth is only available on enterprise plans. Reach out to us at info@hyperbrowser.ai to learn more.

Proxies

Route sessions through proxies for geo-targeting or additional anonymity:

const session = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
});

session = client.sessions.create(params={"use_proxy": True, "proxy_country": "US"})

from hyperbrowser.models import CreateSessionParams

session = client.sessions.create(
    params=CreateSessionParams(use_proxy=True, proxy_country="US")
)

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useProxy": true,
    "proxyCountry": "US"
  }'

See the Proxy Guide for advanced proxy configuration including states, cities, and custom proxy servers.

Session Timeout

Sessions automatically close after a certain amount of time based on your team’s default timeout setting. You can change the default timeout on the Settings page. You can also configure the timeout per session during session creation:

const session = await client.sessions.create({
  timeoutMinutes: 60, // 1 hour
});

session = client.sessions.create(params={"timeout_minutes": 60})

from hyperbrowser.models import CreateSessionParams

session = client.sessions.create(params=CreateSessionParams(timeout_minutes=60))

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeoutMinutes": 60}'

Custom Screen Size

Set custom screen dimensions for specific testing scenarios:

const session = await client.sessions.create({
  screen: {
    width: 1920,
    height: 1080,
  },
});

session = client.sessions.create(params={"screen": {"width": 1920, "height": 1080}})

from hyperbrowser.models import CreateSessionParams, ScreenConfig

session = client.sessions.create(
    params=CreateSessionParams(screen=ScreenConfig(width=1920, height=1080))
)

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "screen": {
      "width": 1920,
      "height": 1080
    }
  }'

Next Steps

Lifecycle Management

Stop, monitor, and manage active sessions

Connect with Playwright

Use Playwright to control your session

Connect with Puppeteer

Use Puppeteer to control your session

Stealth Mode

Deep dive into anti-detection features

Get Started

Browser Sessions

Session Configuration

Web API

Agents

HyperAgent Usage

Scraping

Webhooks

Integrations

Quick Start

Configuration Options

Common Configuration Options

Session Response

Stealth Mode

Proxies

Session Timeout

Custom Screen Size

Next Steps

Lifecycle Management

Connect with Playwright

Connect with Puppeteer

Stealth Mode