# Scrapfly Documentation ## Table of Contents ### Dashboard - [Intro](https://scrapfly.io/docs) - [Project](https://scrapfly.io/docs/project) - [Account](https://scrapfly.io/docs/account) - [Workspace & Team](https://scrapfly.io/docs/workspace-and-team) - [Billing](https://scrapfly.io/docs/billing) ### Products #### MCP Server - [Getting Started](https://scrapfly.io/docs/mcp/getting-started) - [Tools & API Spec](https://scrapfly.io/docs/mcp/tools) - [Authentication](https://scrapfly.io/docs/mcp/authentication) - [Examples & Use Cases](https://scrapfly.io/docs/mcp/examples) - [FAQ](https://scrapfly.io/docs/mcp/faq) ##### Integrations - [Overview](https://scrapfly.io/docs/mcp/integrations) - [Claude Desktop](https://scrapfly.io/docs/mcp/integrations/claude-desktop) - [Claude Code](https://scrapfly.io/docs/mcp/integrations/claude-code) - [ChatGPT](https://scrapfly.io/docs/mcp/integrations/chatgpt) - [Cursor](https://scrapfly.io/docs/mcp/integrations/cursor) - [Cline](https://scrapfly.io/docs/mcp/integrations/cline) - [Windsurf](https://scrapfly.io/docs/mcp/integrations/windsurf) - [Zed](https://scrapfly.io/docs/mcp/integrations/zed) - [Roo Code](https://scrapfly.io/docs/mcp/integrations/roo-code) - [VS Code](https://scrapfly.io/docs/mcp/integrations/vscode) - [LangChain](https://scrapfly.io/docs/mcp/integrations/langchain) - [LlamaIndex](https://scrapfly.io/docs/mcp/integrations/llamaindex) - [CrewAI](https://scrapfly.io/docs/mcp/integrations/crewai) - [OpenAI](https://scrapfly.io/docs/mcp/integrations/openai) - [n8n](https://scrapfly.io/docs/mcp/integrations/n8n) - [Make](https://scrapfly.io/docs/mcp/integrations/make) - [Zapier](https://scrapfly.io/docs/mcp/integrations/zapier) - [Vapi AI](https://scrapfly.io/docs/mcp/integrations/vapi) - [Agent Builder](https://scrapfly.io/docs/mcp/integrations/agent-builder) - [Custom Client](https://scrapfly.io/docs/mcp/integrations/custom-client) #### Web Scraping API - [Getting Started](https://scrapfly.io/docs/scrape-api/getting-started) - [API Specification]() - [Monitoring](https://scrapfly.io/docs/monitoring) - [Customize Request](https://scrapfly.io/docs/scrape-api/custom) - [Debug](https://scrapfly.io/docs/scrape-api/debug) - [Anti Scraping Protection](https://scrapfly.io/docs/scrape-api/anti-scraping-protection) - [Proxy](https://scrapfly.io/docs/scrape-api/proxy) - [Proxy Mode](https://scrapfly.io/docs/scrape-api/proxy-mode) - [Proxy Mode - Screaming Frog](https://scrapfly.io/docs/scrape-api/proxy-mode/screaming-frog) - [Proxy Mode - Apify](https://scrapfly.io/docs/scrape-api/proxy-mode/apify) - [(Auto) Data Extraction](https://scrapfly.io/docs/scrape-api/extraction) - [Javascript Rendering](https://scrapfly.io/docs/scrape-api/javascript-rendering) - [Javascript Scenario](https://scrapfly.io/docs/scrape-api/javascript-scenario) - [SSL](https://scrapfly.io/docs/scrape-api/ssl) - [DNS](https://scrapfly.io/docs/scrape-api/dns) - [Cache](https://scrapfly.io/docs/scrape-api/cache) - [Session](https://scrapfly.io/docs/scrape-api/session) - [Webhook](https://scrapfly.io/docs/scrape-api/webhook) - [Screenshot](https://scrapfly.io/docs/scrape-api/screenshot) - [Errors](https://scrapfly.io/docs/scrape-api/errors) - [Timeout](https://scrapfly.io/docs/scrape-api/understand-timeout) - [Throttling](https://scrapfly.io/docs/throttling) - [Troubleshoot](https://scrapfly.io/docs/scrape-api/troubleshoot) - [Billing](https://scrapfly.io/docs/scrape-api/billing) - [FAQ](https://scrapfly.io/docs/scrape-api/faq) #### Crawler API - [Getting Started](https://scrapfly.io/docs/crawler-api/getting-started) - [API Specification]() - [Retrieving Results](https://scrapfly.io/docs/crawler-api/results) - [WARC Format](https://scrapfly.io/docs/crawler-api/warc-format) - [Data Extraction](https://scrapfly.io/docs/crawler-api/extraction-rules) - [Webhook](https://scrapfly.io/docs/crawler-api/webhook) - [Billing](https://scrapfly.io/docs/crawler-api/billing) - [Errors](https://scrapfly.io/docs/crawler-api/errors) - [Troubleshoot](https://scrapfly.io/docs/crawler-api/troubleshoot) - [FAQ](https://scrapfly.io/docs/crawler-api/faq) #### Screenshot API - [Getting Started](https://scrapfly.io/docs/screenshot-api/getting-started) - [API Specification]() - [Accessibility Testing](https://scrapfly.io/docs/screenshot-api/accessibility) - [Webhook](https://scrapfly.io/docs/screenshot-api/webhook) - [Billing](https://scrapfly.io/docs/screenshot-api/billing) - [Errors](https://scrapfly.io/docs/screenshot-api/errors) #### Extraction API - [Getting Started](https://scrapfly.io/docs/extraction-api/getting-started) - [API Specification]() - [Rules Template](https://scrapfly.io/docs/extraction-api/rules-and-template) - [LLM Extraction](https://scrapfly.io/docs/extraction-api/llm-prompt) - [AI Auto Extraction](https://scrapfly.io/docs/extraction-api/automatic-ai) - [Webhook](https://scrapfly.io/docs/extraction-api/webhook) - [Billing](https://scrapfly.io/docs/extraction-api/billing) - [Errors](https://scrapfly.io/docs/extraction-api/errors) - [FAQ](https://scrapfly.io/docs/extraction-api/faq) #### Proxy Saver - [Getting Started](https://scrapfly.io/docs/proxy-saver/getting-started) - [Fingerprints](https://scrapfly.io/docs/proxy-saver/fingerprints) - [Optimizations](https://scrapfly.io/docs/proxy-saver/optimizations) - [SSL Certificates](https://scrapfly.io/docs/proxy-saver/certificates) - [Protocols](https://scrapfly.io/docs/proxy-saver/protocols) - [Pacfile](https://scrapfly.io/docs/proxy-saver/pacfile) - [Secure Credentials](https://scrapfly.io/docs/proxy-saver/security) - [Billing](https://scrapfly.io/docs/proxy-saver/billing) #### Cloud Browser API - [Getting Started](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Proxy & Geo-Targeting](https://scrapfly.io/docs/cloud-browser-api/proxy) - [Unblock API](https://scrapfly.io/docs/cloud-browser-api/unblock) - [File Downloads](https://scrapfly.io/docs/cloud-browser-api/file-downloads) - [Session Resume](https://scrapfly.io/docs/cloud-browser-api/session-resume) - [Human-in-the-Loop](https://scrapfly.io/docs/cloud-browser-api/human-in-the-loop) - [Debug Mode](https://scrapfly.io/docs/cloud-browser-api/debug-mode) - [Bring Your Own Proxy](https://scrapfly.io/docs/cloud-browser-api/bring-your-own-proxy) - [Browser Extensions](https://scrapfly.io/docs/cloud-browser-api/extensions) ##### Integrations - [Puppeteer](https://scrapfly.io/docs/cloud-browser-api/puppeteer) - [Playwright](https://scrapfly.io/docs/cloud-browser-api/playwright) - [Selenium](https://scrapfly.io/docs/cloud-browser-api/selenium) - [Vercel Agent Browser](https://scrapfly.io/docs/cloud-browser-api/agent-browser) - [Browser Use](https://scrapfly.io/docs/cloud-browser-api/browser-use) - [Stagehand](https://scrapfly.io/docs/cloud-browser-api/stagehand) - [Billing](https://scrapfly.io/docs/cloud-browser-api/billing) - [Errors](https://scrapfly.io/docs/cloud-browser-api/errors) ### Tools - [Antibot Detector](https://scrapfly.io/docs/tools/antibot-detector) ### SDK - [Golang](https://scrapfly.io/docs/sdk/golang) - [Python](https://scrapfly.io/docs/sdk/python) - [TypeScript](https://scrapfly.io/docs/sdk/typescript) - [Scrapy](https://scrapfly.io/docs/sdk/scrapy) ### Integrations - [Getting Started](https://scrapfly.io/docs/integration/getting-started) - [LangChain](https://scrapfly.io/docs/integration/langchain) - [LlamaIndex](https://scrapfly.io/docs/integration/llamaindex) - [CrewAI](https://scrapfly.io/docs/integration/crewai) - [Zapier](https://scrapfly.io/docs/integration/zapier) - [Make](https://scrapfly.io/docs/integration/make) - [n8n](https://scrapfly.io/docs/integration/n8n) ### Academy - [Overview](https://scrapfly.io/academy) - [Web Scraping Overview](https://scrapfly.io/academy/scraping-overview) - [Tools](https://scrapfly.io/academy/tools-overview) - [Reverse Engineering](https://scrapfly.io/academy/reverse-engineering) - [Static Scraping](https://scrapfly.io/academy/static-scraping) - [HTML Parsing](https://scrapfly.io/academy/html-parsing) - [Dynamic Scraping](https://scrapfly.io/academy/dynamic-scraping) - [Hidden API Scraping](https://scrapfly.io/academy/hidden-api-scraping) - [Headless Browsers](https://scrapfly.io/academy/headless-browsers) - [Hidden Web Data](https://scrapfly.io/academy/hidden-web-data) - [JSON Parsing](https://scrapfly.io/academy/json-parsing) - [Data Processing](https://scrapfly.io/academy/data-processing) - [Scaling](https://scrapfly.io/academy/scaling) - [Walkthrough Summary](https://scrapfly.io/academy/walkthrough-summary) - [Scraper Blocking](https://scrapfly.io/academy/scraper-blocking) - [Proxies](https://scrapfly.io/academy/proxies) --- # Getting Started with Cloud Browser [ View as markdown ](https://scrapfly.io/?view=markdown) Copy for LLM Copy for LLM [ Open in ChatGPT ](https://chatgpt.com/?hints=search&prompt=Read%20from%20https%3A%2F%2Fscrapfly.io%2Fdocs%2Fcloud-browser-api%2Fgetting-started%20so%20I%20can%20ask%20questions%20about%20it.) [ Open in Claude ](https://claude.ai/new?q=Read%20from%20https%3A%2F%2Fscrapfly.io%2Fdocs%2Fcloud-browser-api%2Fgetting-started%20so%20I%20can%20ask%20questions%20about%20it.) [ Open in Perplexity ](https://www.perplexity.ai/search/new?q=Read%20from%20https%3A%2F%2Fscrapfly.io%2Fdocs%2Fcloud-browser-api%2Fgetting-started%20so%20I%20can%20ask%20questions%20about%20it.) **Cloud Browser** provides remote browser sessions accessible via WebSocket using the [Chrome DevTools Protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/). 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](https://scrapfly.io/docs/cloud-browser-api/session-resume) ##### Human-in-the-Loop Take [manual control](https://scrapfly.io/docs/cloud-browser-api/human-in-the-loop) of sessions for debugging and CAPTCHA solving ##### Debug Mode [Record sessions](https://scrapfly.io/docs/cloud-browser-api/debug-mode) 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](https://scrapfly.io/docs/cloud-browser-api/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). | | `debug` | No | `false` | Enable session recording for debugging. See [Debug Mode](https://scrapfly.io/docs/cloud-browser-api/debug-mode). | | `block_images` | No | `false` | Stub image requests with a transparent 1x1 pixel. Reduces bandwidth while remaining invisible to anti-bot systems. | | `block_styles` | No | `false` | Stub stylesheet requests with an empty CSS response. | | `block_fonts` | No | `false` | Stub font requests with an empty response. | | `block_media` | No | `false` | Stub video and audio media requests. | | `blacklist` | No | `false` | Stub known analytics, tracking, and telemetry URLs. | | `cache` | No | `false` | Enable HTTP cache for static resources. Cached bandwidth billed at 1 credit/MB. | **Stubbing vs Blocking:** Resources are **stubbed**, not blocked — the browser receives a valid but empty response (e.g. a transparent 1x1 pixel for images). This saves bandwidth while remaining invisible to anti-bot systems that detect blocked requests. ## No-Effect CDP Commands Cloud Browser automatically manages browser fingerprinting, emulation, and device metrics to provide optimal anti-detection and consistency. As a result, the following CDP commands are **silently ignored** when sent through the WebSocket connection: These commands will **not** cause errors or break your automation — they are accepted and return a successful response, but they have **no effect** on the browser session. Cloud Browser handles these settings internally based on your connection parameters (`os`, `country`, etc.). | CDP Command | Description | |---|---| | `Emulation.setDeviceMetricsOverride` | Device screen dimensions, pixel ratio, and mobile emulation | | `Emulation.setUserAgentOverride` | User-Agent string, platform, and client hints | | `Emulation.setTimezoneOverride` | Browser timezone | | `Emulation.setLocaleOverride` | Browser locale and language settings | | `Emulation.setHardwareConcurrencyOverride` | Number of CPU cores reported by `navigator.hardwareConcurrency` | | `Emulation.setVisibleSize` | Visible viewport size | | `Emulation.setEmulatedMedia` | Media type and feature overrides (e.g. `prefers-color-scheme`) | | `Emulation.setDefaultBackgroundColorOverride` | Default background color override | | `Emulation.setNavigatorOverrides` | Navigator platform override | | `Emulation.setPageScaleFactor` | Page zoom/scale factor | If you need to control any of these settings, use the [connection parameters](#parameters) instead (e.g. `os` for OS fingerprinting, `country` for locale/timezone). ## 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 ](https://scrapfly.io/docs/cloud-browser-api/puppeteer) [ Playwright ](https://scrapfly.io/docs/cloud-browser-api/playwright) [ Selenium ](https://scrapfly.io/docs/cloud-browser-api/selenium) **AI Agent Frameworks** [ Browser Use ](https://scrapfly.io/docs/cloud-browser-api/browser-use) [ Stagehand ](https://scrapfly.io/docs/cloud-browser-api/stagehand) **Direct CDP** [ Raw WebSocket ](#puppeteer-example) [ CDP Documentation ](https://chromedevtools.github.io/devtools-protocol/) ## Quick Start Examples Connect to Cloud Browser using your preferred automation tool: Python SDK Python (Playwright) JavaScript (Puppeteer) JavaScript (Playwright) Browser Use ``` from scrapfly import ScrapflyClient, BrowserConfig from playwright.sync_api import sync_playwright client = ScrapflyClient(key='{{ YOUR_API_KEY }}') config = BrowserConfig( proxy_pool='datacenter', os='linux', ) with sync_playwright() as p: browser = p.chromium.connect_over_cdp(client.cloud_browser(config)) 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() ``` ``` from playwright.sync_api import sync_playwright API_KEY = '{{ YOUR_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() ``` ``` const puppeteer = require('puppeteer-core'); const API_KEY = '{{ YOUR_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(); ``` ``` const { chromium } = require('playwright'); const API_KEY = '{{ YOUR_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(); ``` ``` import asyncio from browser_use import Agent, Browser, BrowserProfile from langchain_openai import ChatOpenAI API_KEY = '{{ YOUR_API_KEY }}' BROWSER_WS = f'wss://browser.scrapfly.io?api_key={API_KEY}&proxy_pool=datacenter&os=linux' async def run_agent(): # Connect to Cloud Browser via CDP browser = Browser( browser_profile=BrowserProfile( cdp_url=BROWSER_WS, ) ) # Create AI agent with natural language task agent = Agent( task="Go to https://web-scraping.dev and find the product prices", llm=ChatOpenAI(model="gpt-4o"), browser=browser, ) # Run the agent result = await agent.run() print("Agent result:", result) asyncio.run(run_agent()) ``` ## Billing Cloud Browser uses a billing model based on session time, bandwidth, and optional cached bandwidth: Time (per 30s) - All proxy types **1 credit** Bandwidth (per MB) - Datacenter **2 credits** - Residential **10 credits** Cached BW (per MB) - All proxy types **1 credit** Minimum 5 credits per session. See [Billing](https://scrapfly.io/docs/cloud-browser-api/billing) for details. ## Troubleshooting ##### WebSocket Connection Failed **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 ##### Session Not Persisting **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. ##### Browser Disconnects Unexpectedly **Cause:** Browser session timeout or crash. **Solution:** - Always call `browser.close()` to properly terminate sessions - Implement reconnection logic in your automation - Monitor your scripts for memory leaks or infinite loops ## Related Documentation - [Session Resume](https://scrapfly.io/docs/cloud-browser-api/session-resume) - Reconnect to existing browser sessions - [Human-in-the-Loop](https://scrapfly.io/docs/cloud-browser-api/human-in-the-loop) - Take manual control of sessions for debugging - [Debug Mode](https://scrapfly.io/docs/cloud-browser-api/debug-mode) - Record sessions as videos for analysis - [File Downloads](https://scrapfly.io/docs/cloud-browser-api/file-downloads) - Retrieve downloaded files from browser sessions - [Cloud Browser Billing](https://scrapfly.io/docs/cloud-browser-api/billing) - Detailed pricing and cost calculation - [Puppeteer Integration](https://scrapfly.io/docs/cloud-browser-api/puppeteer) - Full Puppeteer setup guide - [Playwright Integration](https://scrapfly.io/docs/cloud-browser-api/playwright) - Full Playwright setup guide - [Browser Use Integration](https://scrapfly.io/docs/cloud-browser-api/browser-use) - AI agent framework setup - [Stagehand Integration](https://scrapfly.io/docs/cloud-browser-api/stagehand) - AI-powered browser automation setup - [No-Effect CDP Commands](#no-effect-cdp-commands) - CDP commands silently ignored by Cloud Browser - [Error Reference](https://scrapfly.io/docs/cloud-browser-api/errors) - All Cloud Browser API errors and troubleshooting - [General Billing Overview](https://scrapfly.io/docs/billing) - Account-wide billing information