Quickstart

Open Google in a cloud browser using a Surfsky SDK or your existing automation framework.

Before you start

Get your API token and API base URL from the Surfsky dashboard. Replace YOUR_API_TOKEN and https://YOUR_API_HOST below with your account’s values.

export SURFSKY_API_TOKEN="YOUR_API_TOKEN"
export SURFSKY_API_BASE_URL="https://YOUR_API_HOST"

Keep the token in your server environment, outside source control. These examples omit proxy to use the default pool available to your account. If your account has no pool, provide your own proxy as described in Proxies.

SDK quickstart

Python
JavaScript / TypeScript

Requires Python 3.12 or newer.

pip install surfsky

uv init # For a new project
uv add surfsky

Save as first_browser.py:

import asyncio
from surfsky import AsyncSurfsky


async def main():
    # Or: AsyncSurfsky(api_token="YOUR_API_TOKEN", base_url="https://YOUR_API_HOST")
    async with AsyncSurfsky() as client:
        async with client.browser() as browser:
            await browser.goto("https://www.google.com")
            print(await browser.title())


asyncio.run(main())

python first_browser.py

uv run first_browser.py

Requires Node.js 22+ or Bun.

npm install surfsky

bun add surfsky

Save as first-browser.mjs:

import { Surfsky } from "surfsky";

// Or: new Surfsky({ apiToken: "YOUR_API_TOKEN", baseUrl: "https://YOUR_API_HOST" });
const client = new Surfsky();
const browser = await client.browser();
try {
  await browser.goto("https://www.google.com");
  console.log(await browser.title());
} finally {
  await browser.close();
}

node first-browser.mjs

bun first-browser.mjs

Both examples stop the session on completion or error. If cleanup fails, the browser stops after its inactivity timeout.

Connect your existing code

Follow the guide for your framework:

Using the API directly

1. Start a browser

One-time
Persistent

curl --fail-with-body "$SURFSKY_API_BASE_URL/profiles/one_time" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Create a profile once:

curl --fail-with-body "$SURFSKY_API_BASE_URL/profiles" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My profile", "fingerprint": {"os": "win"}}' # os: win, mac, or android

Replace PROFILE_UUID with data.uuid from the response, then start it:

curl --fail-with-body "$SURFSKY_API_BASE_URL/profiles/PROFILE_UUID/start" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "success": true,
  "internal_uuid": "a8fb62f90611456aa75422b01c385a62",
  "ws_url": "wss://YOUR_API_HOST/proxy/a8fb62f90611456aa75422b01c385a62"
}

2. Connect

Pass the returned ws_url to your framework’s CDP connection method. Use the existing browser context to work with the profile’s state. The default inactivity timeout is 30 seconds. To allow more time, set inactive_kill_timeout in the start request. For example, "browser_settings": {"inactive_kill_timeout": 300} allows 300 seconds of inactivity. To interact with the browser through HTTP requests, use the Scraping API with the returned internal_uuid.

3. Stop it

A running browser occupies 1 browser slot until it stops.

You can stop the browser in 3 ways:

Call a method that closes the remote browser, such as Puppeteer’s browser.close().
Leave it idle until inactive_kill_timeout expires.
Send the stop request below.

Replace INTERNAL_UUID with the value from your start response:

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

Playwright’s browser.close() over CDP only disconnects. Use the stop request or close it through CDP to end the session immediately.

If the example fails

Error	Check
`not_authorized`	The token is set and has no leading or trailing whitespace.
`namespace_not_allowed`	The base URL matches the one assigned to your account.
`proxy_required` or `proxy_pool_unavailable`	Your account has a proxy pool, or the start request supplies your own proxy.
`parallel_browsers_limit_reached`	An existing browser must stop before another can start.

See Errors for other API failures. Continue with Sessions to reuse browser state, or the Python and TypeScript SDK guides for browser actions and pooling.

Get started

Connect your tools

Browser sessions

Browser actions

CAPTCHA guides

Debugging

Performance and limits

About Surfsky

Before you start

SDK quickstart

Connect your existing code

Using the API directly

1. Start a browser

2. Connect

3. Stop it

If the example fails

​Before you start

​SDK quickstart

​Connect your existing code

​Using the API directly

​1. Start a browser

​2. Connect

​3. Stop it

​If the example fails

Before you start

SDK quickstart

Connect your existing code

Using the API directly

1. Start a browser

2. Connect

3. Stop it

If the example fails