surfsky

Python SDK for Surfsky, a cloud-based antidetect browser.

• Talks plain CDP, with none of the traces Playwright, Puppeteer or Selenium leave behind: no Runtime.enable, no injected scripts, no extra globals.
• Clicks, scrolls and keystrokes go through Surfsky's server-side human emulation, with real mouse paths and per-key timing. The page gets trusted events.
• Residential and mobile proxies, 100M+ IPs, picked by country, region or city. Or bring your own.
• Fingerprints from a pool of 2.5M+ real devices. Persistent profiles keep the same identity between runs.
• A browser pool that keeps every slot in your plan busy.
• Nothing to install. Browsers run in Surfsky's cloud. Playwright-style API, sync and async clients, fully typed.

API reference for the service itself: https://docs.surfsky.io/api-reference

Installation

uv add surfsky

or, with pip:

pip install surfsky

Requires Python 3.12 or newer.

Quick start

Sign up at surfsky.io. Once you're logged in, the dashboard shows your API token and base URL. Put them in the environment:

export SURFSKY_API_TOKEN=...
export SURFSKY_API_BASE_URL=...

Then start a browser and use it:

import asyncio

from surfsky import AsyncSurfsky, SharedProxy


async def main():
    # or AsyncSurfsky(api_token="...", base_url="...") instead of env vars
    async with AsyncSurfsky() as client:
        # starts a session, stops it on exit so it doesn't keep billing
        async with client.browser(proxy=SharedProxy(country="us")) as browser:
            await browser.goto("https://duckduckgo.com", wait_until="domcontentloaded")
            await browser.type('[name="q"]', "surfsky cloud browser")
            await browser.click("#searchbox_homepage button[type=submit]")
            print(await browser.wait_for_url("?q="))


asyncio.run(main())

More examples in examples/.

Browser automation

The API sticks to Playwright's names and semantics where it can: click, fill, hover, wait_for_selector, inner_text, select_option, keyboard.press, mouse.move and so on. Input goes through Surfsky's human emulation. Reads use plain CDP and run no JavaScript in the page.

When you need JavaScript:

await browser.evaluate("document.title")
await browser.evaluate("(a, b) => a + b", 1, 2)

Scripts run in an isolated world the page can't see. Pass isolated=False to use the page's own context.

Also useful:

• client.browser(block_resources={"image", "font", "media"}) skips those downloads and saves proxy traffic.

• Grab the JSON a page fetches instead of parsing its HTML:

  await browser.capture_responses("/api/search")
  await browser.goto(url)
  data = (await browser.wait_for_response("/api/search")).json()
  

• Work with several pages at once. browser.pages has every open tab, popups included, and new_page() adds one:

  await browser.new_page()
  await browser.pages[1].goto("https://example.com")
  print(await browser.pages[0].title(), await browser.pages[1].title())
  

Every method is listed in the API reference.

Running multiple browsers

client.map runs a function over a list of items in parallel, one browser per item, and collects the results:

async def title(browser, url):
    await browser.goto(url)
    return await browser.title()

for o in await client.map(title, urls):
    print(o.item, o.value if o.ok else o.error)

Errors land in o.error instead of raising, so one bad page doesn't stop the run. By default the pool uses every browser your plan allows (concurrency="auto"). Pass concurrency=5 to cap it.

If you need more control, write your own loop on top of the pool:

async with client.browsers() as pool:
    async with pool.lease() as browser:      # waits for a free browser
        if not browser.data.get("logged_in"):
            await log_in(browser)
            browser.data["logged_in"] = True
        ...
        if looks_blocked:
            browser.retire()                 # next lease gets a fresh identity

A browser keeps its fingerprint, proxy and cookies between leases until you retire it.

Using Playwright or Puppeteer

You don't have to use the SDK's browser API. client.session starts a browser and gives you its WebSocket URL, so Playwright, Puppeteer or any other CDP client can drive it. The SDK then handles profiles, proxies and session lifecycle:

from playwright.sync_api import sync_playwright
from surfsky import Surfsky

with Surfsky() as client, client.session() as session, sync_playwright() as pw:
    browser = pw.chromium.connect_over_cdp(session.connect_url)
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")

Don't use stock Playwright or Puppeteer. Both leave automation traces the SDK goes out of its way to avoid, Runtime.enable above all. Use one of the patched forks that strip those traces. They're drop-in replacements.

Selenium works too (enable_chromedriver=True, see examples/selenium_connect.py) but isn't recommended: chromedriver is easy to detect.

Proxies

Every session start accepts proxy=. Bring your own, or use Surfsky's built-in pools:

• Premium: clean residential and mobile IPs, targeted by country, region or city. Use it for production.
• Shared: a pool for testing. Don't rely on it against sites that matter.

from surfsky import PremiumProxy, ProxyCycle, ProxyGeo, ProxyTemplate, SharedProxy

proxy = PremiumProxy(country="us", region="ny", type="mobile")  # Surfsky premium
proxy = SharedProxy(country="us")                              # Surfsky shared, for tests
proxy = ProxyGeo(country="de")                                 # premium if set up, else shared
proxy = "socks5://user:pass@host:1080"                         # your own
proxy = ProxyCycle(my_proxies)                                 # round-robin over your own list
proxy = ProxyTemplate("http://user-sessid-{session}:pw@gate.example.com:7000")

client.proxies lists the available countries, regions and cities, and your quota.

Profiles and the REST API

Profiles, proxies, fingerprints, extensions and account limits are all typed calls on the client. Profiles are the ones you'll use most: a profile is a saved identity, and every session started on it gets the same fingerprint, proxy and cookies.

from surfsky import AsyncSurfsky, Fingerprint, PremiumProxy

async with AsyncSurfsky() as client:
    profile = await client.profiles.create(
        title="account-1",
        fingerprint=Fingerprint(os="win", os_arch="x86", os_version="11"),
        proxy=PremiumProxy(country="us"),
    )
    async with client.browser(profile_uuid=profile.uuid) as browser:
        await browser.goto("https://example.com/login")
        ...  # log in once, the cookies stay with the profile

Next time, client.browser(profile_uuid=...) brings back the same identity, still logged in. client.profiles.iter_all() lists your profiles and delete(uuid) removes one.

The sync client, Surfsky, has the same REST calls without the browser API. For endpoints the SDK doesn't cover, client.request(method, path, ...) sends the request and returns the raw httpx.Response.

API reference

Every browser method is async. Browser is a Page plus the connection: page methods on it act on the session's first tab. Waits take timeout in seconds, default 30, and raise BrowserTimeoutError.

Client

AsyncSurfsky(api_token=None, base_url=None, timeout=30, max_retries=3, backoff_factor=0.5). Surfsky is the sync client, REST only.

Session options: fingerprint, proxy, browser_settings (inactive_kill_timeout, cache_enabled, cache_key), enable_chromedriver, extensions (up to 5 uuids), proxy_blacklist, domain_routes, cookies. fingerprint and cookies apply to one-time sessions only.

Pool

The plan limit counts browsers started elsewhere with the same token. lease() waits for one of its own and raises RateLimitError only if it has none.

Navigation

Reading

Input

Server-side human emulation. The first CSS match is used. click, dblclick and hover also take wait_for_visible, scroll_into_view, pre_delay, post_delay, timeout.

Script

Cookies and storage

Network

Dialogs

page.on_dialog = handler(kind, message). kind: alert, confirm, prompt, beforeunload. Return True to accept, False to dismiss, a string to answer a prompt, None for the default. Default: dismiss, except beforeunload is accepted.

Pages

REST

Same on both clients.

Errors

All subclasses of SurfskyError. HTTP: APIError subclasses named after the status (NotFoundError, RateLimitError, ...). Browser: CDPError, BrowserTimeoutError, PageClosedError. Idempotent requests retry on 429, 5xx and connection errors. POST and PATCH retry on 429 only, so a lost reply can't start a second billed session.

Examples

More examples in examples/. Install the extras first:

uv sync --group examples

Development

uv sync --all-extras
uv run ruff check . && uv run ty check && uv run pytest

Live tests start real sessions and bill your account:

SURFSKY_LIVE_TESTS=1 SURFSKY_API_TOKEN=... uv run pytest tests/test_live_concurrency.py

License

MIT