Playwright

Playwright attaches to a Surfsky browser through the session’s CDP WebSocket URL. Use connect_over_cdp in Python or connectOverCDP in the other languages instead of launching a browser. The browser runs in Surfsky’s cloud; no local Chromium is needed.

Standard Playwright creates utility worlds, helper scripts, and bindings that detection scripts can identify. Use a patched fork such as Patchright or rebrowser-playwright for sites with bot protection.

Prerequisites

Set your API token and base URL. The examples start a browser with an empty request body, which uses your account’s default proxy pool. Proxy, fingerprint, and other start options are in the API reference.

Run an example

Each example starts a one-time browser, connects, opens a page, prints its title, and closes the browser. To keep cookies and login state between runs, start a persistent profile instead; the connection code is the same.

Python
JavaScript
Java
.NET

pip install playwright requests

Save as surfsky_playwright.py:

import os
import requests
from playwright.sync_api import sync_playwright

base_url = os.environ["SURFSKY_API_BASE_URL"].rstrip("/")
headers = {"X-Cloud-Api-Token": os.environ["SURFSKY_API_TOKEN"]}

response = requests.post(f"{base_url}/profiles/one_time", json={}, headers=headers, timeout=120)
response.raise_for_status()
session = response.json()

with sync_playwright() as playwright:
    browser = playwright.chromium.connect_over_cdp(session["ws_url"])
    context = browser.contexts[0]
    page = context.pages[0] if context.pages else context.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.new_browser_cdp_session().send("Browser.close")

python surfsky_playwright.py

Requires Node.js 22 or newer.

npm install playwright-core

Save as surfsky-playwright.mjs:

import { chromium } from "playwright-core";

const baseUrl = process.env.SURFSKY_API_BASE_URL.replace(/\/+$/, "");
const headers = {
  "X-Cloud-Api-Token": process.env.SURFSKY_API_TOKEN,
  "Content-Type": "application/json",
};

const response = await fetch(`${baseUrl}/profiles/one_time`, {
  method: "POST",
  headers,
  body: "{}",
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok)
  throw new Error(`Start failed: ${response.status} ${await response.text()}`);
const session = await response.json();

const browser = await chromium.connectOverCDP(session.ws_url);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
console.log(await page.title());
const cdp = await browser.newBrowserCDPSession();
await cdp.send("Browser.close");

node surfsky-playwright.mjs

Add Playwright to your project using the official instructions. Start a browser with the REST quickstart and export the returned ws_url as SURFSKY_WS_URL.

import com.microsoft.playwright.*;

public class SurfskyExample {
    public static void main(String[] args) {
        String wsUrl = System.getenv("SURFSKY_WS_URL");
        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().connectOverCDP(wsUrl);
            BrowserContext context = browser.contexts().get(0);
            Page page = context.pages().isEmpty() ? context.newPage() : context.pages().get(0);
            page.navigate("https://example.com");
            System.out.println(page.title());
            browser.newBrowserCDPSession().send("Browser.close");
        }
    }
}

dotnet add package Microsoft.Playwright

Start a browser with the REST quickstart and export the returned ws_url as SURFSKY_WS_URL. Put this in Program.cs:

using Microsoft.Playwright;

var wsUrl = Environment.GetEnvironmentVariable("SURFSKY_WS_URL");
using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.ConnectOverCDPAsync(wsUrl);
var context = browser.Contexts[0];
var page = context.Pages.Count > 0 ? context.Pages[0] : await context.NewPageAsync();
await page.GotoAsync("https://example.com");
Console.WriteLine(await page.TitleAsync());
var cdp = await browser.NewBrowserCDPSessionAsync();
await cdp.SendAsync("Browser.close");

Run with dotnet run.

Expected output:

Example Domain

Stop the session

Playwright’s browser.close() only disconnects from a browser attached over CDP. Stop the session either through CDP, as the examples do:

browser.new_browser_cdp_session().send("Browser.close")

or through the API with the internal_uuid from the start response:

curl --fail-with-body -X POST \
  "$SURFSKY_API_BASE_URL/profiles/INTERNAL_UUID/stop" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN"

Otherwise the browser stops after the inactivity timeout, 30 seconds by default.

Get started

Connect your tools

Browser sessions

Browser actions

CAPTCHA guides

Debugging

Performance and limits

About Surfsky

Prerequisites

Run an example

Stop the session

​Prerequisites

​Run an example

​Stop the session

Prerequisites

Run an example

Stop the session