Python SDK - Surfsky

Requires Python 3.12 or newer. Install the published surfsky package:

pip install surfsky

Set SURFSKY_API_TOKEN and SURFSKY_API_BASE_URL from the dashboard. See credential setup. You can also pass api_token and base_url to the client constructor.

Start a browser

Save as first_browser.py and run python first_browser.py:

import asyncio
from surfsky import AsyncSurfsky


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


asyncio.run(main())

Expected output is Example Domain. The browser context manager stops the session on exit, including when a page operation raises an exception. Cleanup still requires a running process and a working API connection. AsyncSurfsky provides browser automation and asynchronous REST calls. The synchronous Surfsky client provides REST calls and managed sessions for use with other browser frameworks.

Interact with the page

Page operations run inside the client.browser() block. Common methods include goto, click, type, hover, inner_text, and wait_for_selector. Wait timeouts are in seconds and default to 30; expiration raises BrowserTimeoutError. Use selectors from your target page. For example, in a form with an email field:

await browser.type('input[name="email"]', "[email protected]")
await browser.click('button[type="submit"]')
await browser.wait_for_selector(".confirmation", timeout=15)
print(await browser.inner_text(".confirmation"))

evaluate() executes JavaScript. It uses an isolated execution context by default; pass isolated=False when the script needs variables defined by the page. The DOM is shared, so page code can observe DOM changes made by your script.

print(await browser.evaluate("document.title"))

Save traffic

Pass block_resources when starting the browser:

async with client.browser(block_resources={"image", "font", "media"}) as browser:
    await browser.goto("https://example.com")

Keep resources needed for screenshots, layout, or challenges. See Speed optimization.

Capture a page’s API response

Start capture before the request occurs. Adapt the URL and matching path to your application:

await browser.capture_responses("/api/search")
await browser.goto("https://your-site.example/search")
response = await browser.wait_for_response("/api/search")
data = response.json()

Multiple tabs

browser operates on the first tab. browser.pages includes other tabs and popups:

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

Close tabs you no longer need. See the session page limit.

Running many browsers

This example runs two jobs concurrently and reports each outcome:

import asyncio
from surfsky import AsyncSurfsky


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


async def main():
    async with AsyncSurfsky() as client:
        outcomes = await client.map(
            title,
            ["https://example.com", "https://example.org"],
            concurrency=2,
        )
        for outcome in outcomes:
            print(outcome.value if outcome.ok else outcome.error)


asyncio.run(main())

The pool can reuse browsers between jobs. A leased browser retains its fingerprint, proxy, and cookies between leases. Use browser.retire() to replace it after the current lease when a job needs a fresh identity. For manual leasing:

async with client.browsers(concurrency=2) as pool:
    async with pool.lease() as browser:
        await browser.goto("https://example.com")

Account limits include browsers started by other workers. See Concurrency before distributing work across processes.

Proxies

Pass a proxy choice to browser() or session():

from surfsky import PremiumProxy, SharedProxy

proxy = PremiumProxy(country="us")
# Other choices:
proxy = SharedProxy(country="us")
proxy = "socks5://username:[email protected]:1080"

client.proxies exposes location lookups and quota calls. See Proxies for tier availability and targeting rules.

Sessions

By default, client.browser() starts a one-time session whose state is discarded when it stops. To reuse login state, cookies, and local storage across runs, create a persistent profile and pass its UUID to client.browser(profile_uuid=...). Save this as reuse_session.py. On the first run it creates a profile and saves its UUID in profile-uuid.txt. Later runs read that UUID and restore the same profile:

import asyncio
from pathlib import Path
from surfsky import AsyncSurfsky, Fingerprint, StorageOptions


async def main():
    profile_file = Path("profile-uuid.txt")
    async with AsyncSurfsky() as client:
        if not profile_file.exists():
            profile = await client.profiles.create(
                title="Reusable session",
                fingerprint=Fingerprint(os="win"),
                storage_options=StorageOptions(cookies=True, localstorage=True),
            )
            profile_file.write_text(profile.uuid)

        async with client.browser(profile_uuid=profile_file.read_text().strip()) as browser:
            await browser.goto("https://example.com")
            print("Previous run:", await browser.evaluate('localStorage.getItem("previous-run")'))
            await browser.evaluate('localStorage.setItem("previous-run", "saved")')


asyncio.run(main())

Run python reuse_session.py twice from the same directory, waiting for each run to finish. The first run prints Previous run: None; the second prints Previous run: saved. Surfsky stores the browser state; the local file stores only the profile UUID. The browser context manager stops the session and saves the selected browser state on exit. To reuse a login, replace the example page operations with your site’s sign-in flow on the first run, then open an authenticated page on later runs.

Use Playwright

Use client.session() to let the SDK manage the session while Playwright handles page operations. Install surfsky and playwright, and set the environment variables before running this example:

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)
    try:
        page = browser.contexts[0].pages[0]
        page.goto("https://example.com")
        print(page.title())
    finally:
        browser.close()

The session context stops the remote browser when the block exits.

Raw requests

response = await client.request("GET", "/proxies/shared/quota")
response.raise_for_status()
print(response.json())

request() returns an httpx.Response. Unlike resource methods, it does not raise for an HTTP error unless you call raise_for_status(). The SDK repository includes the full method reference and additional examples.

​Start a browser

​Interact with the page

​Save traffic

​Capture a page’s API response

​Multiple tabs

​Running many browsers

​Proxies

​Sessions

​Use Playwright

​Raw requests