surfsky

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

Install

uv add surfsky

Or pip install surfsky. Requires Python 3.12+.

Quick start

Get your API token and base URL from the dashboard:

export SURFSKY_API_TOKEN='your-token'
export SURFSKY_API_BASE_URL='your-base-url'

import asyncio

from surfsky import AsyncSurfsky, PremiumProxy


async def main():
    async with AsyncSurfsky() as client:
        async with client.browser(proxy=PremiumProxy(country="us")) as browser:
            await browser.goto("https://example.com")
            print(await browser.title())


asyncio.run(main())

The browser context stops the session on exit. Sessions are billed until stopped, including idle time. You can also pass api_token and base_url directly to the client.

Browser methods are async; timeouts are in seconds. Surfsky provides synchronous REST calls. Browser input uses Surfsky's human emulation.

Profiles and proxies

A profile preserves its fingerprint, proxy and cookies across sessions. Inside the client context:

from surfsky import Fingerprint

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")

Reuse the profile ID for subsequent sessions. proxy accepts PremiumProxy for residential or mobile IPs, SharedProxy for testing, or your own proxy URL. client.proxies lists locations and quota.

Parallel browsers

client.map distributes items across a browser pool. Inside the client context:

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


urls = ["https://example.com", "https://example.org"]
for result in await client.map(title, urls, concurrency=2):
    print(result.item, result.value if result.ok else result.error)

Without a concurrency limit, the pool uses your plan's maximum. Results include per-item errors.

To use a browser from the pool:

async with client.browsers() as pool:
    async with pool.lease() as browser:
        await browser.goto("https://example.com")
        print(await browser.title())

lease() waits for a free browser and returns it to the pool on exit. Cookies and browser state persist between leases.

Reference and examples

• SDK API reference
• REST API
• Examples: forms, tabs, retries, profiles, a closed shadow root and CDP connections.

client.session() exposes a CDP URL for external browser clients. See the Playwright and Selenium examples. Install example dependencies with uv sync --group examples.

Development

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

Live tests require credentials and bill your account:

SURFSKY_LIVE_TESTS=1 uv run pytest tests/test_live_concurrency.py

License

MIT