Getting Started with Cloud Browser

View as markdown

Cloud Browser provides remote browser sessions accessible via WebSocket using the Chrome DevTools Protocol (CDP). Connect with Puppeteer, Playwright, Selenium, or AI agent frameworks like Browser Use, Stagehand, and Vibium.

Beta Feature: Cloud Browser is currently in beta and available to staff members only.

Key Features

Remote Browser Sessions

Access real Chrome browsers running in the cloud via CDP WebSocket connections

Proxy Integration

Choose between datacenter or residential proxy networks for geo-targeting

OS Fingerprinting

Emulate Windows, macOS, or Linux browser environments

Session Persistence

Maintain browser state across multiple connections with session resume

Human-in-the-Loop

Take manual control of sessions for debugging and CAPTCHA solving

Debug Mode Coming Soon

Record sessions as videos for debugging and analysis

WebSocket Connection

Connect to Cloud Browser using a CDP-compatible WebSocket URL with your API key and optional parameters:

wss://browser.scrapfly.io?api_key=&proxy_pool=datacenter&os=linux&session=my-session

Connection Parameters

Parameter	Required	Default	Description
`api_key`	Yes	-	Your Scrapfly API key for authentication
`proxy_pool`	No	`datacenter`	Proxy network type: `datacenter` or `residential`
`os`	No	random	Operating system fingerprint: `linux`, `windows`, or `macos`
`session`	No	-	Optional session identifier for maintaining browser state across connections. See Session Resume.
`country`	No	-	Proxy country code (ISO 3166-1 alpha-2), e.g., `us`, `uk`, `de`
`auto_close`	No	`true`	Automatically stop the browser session when the CDP connection disconnects. Set to `false` to keep the browser alive for reconnection.
`timeout`	No	`900`	Maximum session duration in seconds (15 minutes default, 30 minutes max). The session will be forcefully terminated after this time.
`debug` Coming Soon	No	`false`	Enable session recording for debugging. Records the entire session as a video. See Debug Mode.

Integrations

Cloud Browser uses the standard Chrome DevTools Protocol (CDP), making it compatible with all major browser automation tools and AI agent frameworks.

Browser Automation

Puppeteer Playwright Selenium

AI Agent Frameworks

Browser Use Stagehand Vibium

Direct CDP

Raw WebSocket CDP Documentation

Quick Start Examples

Puppeteer

Connect to Cloud Browser using Puppeteer's browserWSEndpoint:

const puppeteer = require('puppeteer-core');

const API_KEY = '';
const BROWSER_WS = `wss://browser.scrapfly.io?api_key=${API_KEY}&proxy_pool=datacenter&os=linux`;

async function run() {
    const browser = await puppeteer.connect({
        browserWSEndpoint: BROWSER_WS,
    });

    const page = await browser.newPage();
    await page.goto('https://web-scraping.dev');

    const title = await page.title();
    console.log('Page title:', title);

    await browser.close();
}

run();

Playwright

Connect using Playwright's CDP endpoint:

const { chromium } = require('playwright');

const API_KEY = '';
const BROWSER_WS = `wss://browser.scrapfly.io?api_key=${API_KEY}&proxy_pool=datacenter&os=linux`;

async function run() {
    const browser = await chromium.connectOverCDP(BROWSER_WS);

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

    await page.goto('https://web-scraping.dev');

    const title = await page.title();
    console.log('Page title:', title);

    await browser.close();
}

run();

Python (Playwright)

Connect using Playwright for Python:

from playwright.sync_api import sync_playwright

API_KEY = ''
BROWSER_WS = f'wss://browser.scrapfly.io?api_key={API_KEY}&proxy_pool=datacenter&os=linux'

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(BROWSER_WS)

    context = browser.contexts[0]
    page = context.pages[0] if context.pages else context.new_page()

    page.goto('https://web-scraping.dev')

    print('Page title:', page.title())

    browser.close()

Browser Use (AI Agent)

Connect Browser Use AI agent to Cloud Browser:

from browser_use import Agent, Browser, BrowserConfig
from langchain_openai import ChatOpenAI

API_KEY = ''
BROWSER_WS = f'wss://browser.scrapfly.io?api_key={API_KEY}&proxy_pool=datacenter&os=linux'

# Configure browser to use Cloud Browser CDP endpoint
browser = Browser(
    config=BrowserConfig(
        cdp_url=BROWSER_WS,
    )
)

# Create AI agent with the cloud browser
agent = Agent(
    task="Go to web-scraping.dev and extract the main heading",
    llm=ChatOpenAI(model="gpt-4o"),
    browser=browser,
)

async def main():
    result = await agent.run()
    print(result)

import asyncio
asyncio.run(main())

Billing

Cloud Browser uses a dual-dimension billing model based on:

Session Time: Billed per 30 seconds (always rounded up)
Bandwidth: Billed per MB consumed (no free threshold)

Time Costs (per 30 seconds)

Datacenter 1 credits
Residential 1 credits

Bandwidth Costs (per MB)

Datacenter 2 credits
Residential 10 credits

For detailed billing information and examples, see the Cloud Browser Billing page.

Troubleshooting

Cause: Invalid API key or network connectivity issues.

Solution:

Verify your API key is correct
Ensure your firewall allows WebSocket connections
Check if you're behind a corporate proxy that blocks WebSocket

Cause: Session ID not provided or session expired.

Solution: Always include the same session parameter in the WebSocket URL for persistent sessions.

const BROWSER_WS = `wss://browser.scrapfly.io?api_key=&session=my-session-id`;

Note: Sessions expire after 1 hour of inactivity by default.

Cause: Browser session timeout or crash.