Skip to main content

View on GitHub

View on PyPI

​
Installation

Install the Hyperbrowser SDK: 
pip install hyperbrowser python-dotenv

​
Quick Start

The Hyperbrowser Python SDK supports both synchronous and asynchronous clients.

​
Synchronous Client

from hyperbrowser import Hyperbrowser
from dotenv import load_dotenv
import os

load_dotenv()

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

# Create a session
session = client.sessions.create()
print(session.ws_endpoint)

​
Asynchronous Client

import asyncio
from hyperbrowser import AsyncHyperbrowser
from dotenv import load_dotenv
import os

load_dotenv()

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

async def main():
    session = await client.sessions.create()
    print(session.ws_endpoint)

asyncio.run(main())

​
Configuration Options

Both clients accept the same configuration parameters: 
from hyperbrowser import Hyperbrowser

client = Hyperbrowser(
    api_key="your-api-key",  # Can also use HYPERBROWSER_API_KEY env var
    base_url="https://api.hyperbrowser.ai",  # Optional, default shown
    timeout=30  # Request timeout in seconds
)

​
Typing Support

The SDK is fully typed end‑to‑end with Pydantic models. Import types from hyperbrowser.models and pass method parameters as model instances. 
from hyperbrowser.models import CreateSessionParams
  • Parameter models: Most methods accept a single Pydantic “params” object (parameter object/DTO). Create an instance and pass only the fields you need — None/unset fields are omitted on the wire.
  • Field names and aliases: Use Pythonic field names in code; the SDK serializes to API field names automatically via serialization_alias (e.g., use_ultra_stealth → useUltraStealth).
  • Responses: Methods return typed Pydantic models.

​
Example: Create a session

from hyperbrowser.models import CreateSessionParams, ScreenConfig

session = client.sessions.create(
    CreateSessionParams(
        accept_cookies=True,
        screen=ScreenConfig(width=1920, height=1080)
    )
)
print("session created", session.id)

​
Integration Examples

from playwright.sync_api import sync_playwright
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import CreateSessionParams
from dotenv import load_dotenv
import os

load_dotenv()

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


def main():
    # Create session
    session = client.sessions.create(params=CreateSessionParams(accept_cookies=True))

    try:
        # Connect with Playwright
        with sync_playwright() as p:
            browser = p.chromium.connect_over_cdp(session.ws_endpoint)
            default_context = browser.contexts[0]
            page = default_context.pages[0]

            page.goto("https://example.com")
            print(f"Page title: {page.title()}")

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


if __name__ == "__main__":
    main()

​
Computer Actions

Programmatically control the browser with low-level actions. For the session-id parameter, you can also just pass in the detailed session object itself, and it is actually recommended to do so.

​
Click

response = client.computer_action.click(
    "session-id",  # or session object
    x=500,
    y=300,
    button="left",  # "left" | "right" | "middle" | "back" | "forward" | "wheel"
    click_count=1,
    return_screenshot=False  # do not return screenshot (default: False)
)

print(response.success)
print(response.screenshot) # base64 if requested

​
Type Text

response = client.computer_action.type_text(
    "session-id",
    text="Hello, World!",
    return_screenshot=False  # do not return screenshot (default: False)
)

​
Press Keys

Uses the xdotool format for keys: https://github.com/sickcodes/xdotool-gui/blob/master/key_list.csv 
response = client.computer_action.press_keys(
    "session-id",
    keys=["Control_L", "a"],  # Key combination
    return_screenshot=False  # do not return screenshot (default: False)
)

​
Move Mouse

response = client.computer_action.move_mouse(
    "session-id",
    x=500,
    y=300,
    return_screenshot=False  # do not return screenshot (default: False)
)

​
Drag

response = client.computer_action.drag(
    "session-id",
    coordinates=[
        {"x": 100, "y": 100},
        {"x": 200, "y": 200},
        {"x": 300, "y": 300}
    ],
    return_screenshot=False  # do not return screenshot (default: False)
)

​
Scroll

response = client.computer_action.scroll(
    "session-id",
    x=500,
    y=300,
    scroll_x=0,
    scroll_y=100,
    return_screenshot=False  # do not return screenshot (default: False)
)

​
Screenshot

response = client.computer_action.screenshot("session-id")
print(response.screenshot)  # base64

​
Support