Cloud Browsers: Persistent, Reusable Browser Profiles

Cloud browsers are saved browser profiles that retain their configuration — viewport, locale, fingerprint settings, cookies, and proxy preferences — between sessions. Unlike temporary Remote CDP sessions, a cloud browser profile persists after you stop the running instance. You can launch it again later, and it picks up exactly where it left off. This makes cloud browsers the right choice for workflows that require a consistent browser identity across multiple visits: account management, multi-session scraping, or any task where a persistent, recognizable browser persona matters.

Lifecycle states

A cloud browser moves through four states during its lifetime:

starting → running → stopping → stopped

starting and stopping still reserve your running allowance — they are not free slots.
running is the only state where connectUrl is present in the API response.
stopped releases running allowance while the saved profile remains.

Poll GET /cloud-browsers/:id to read the actual current state. Display runtime.status exactly as the API returns it; never infer or cache state locally.

Saved profiles vs. running sessions

Saving a profile is free in terms of running quota — a stopped profile occupies a saved profile slot but not a running slot. Only browsers in starting, running, or stopping state consume your concurrent running allowance. Your plan’s allowances are returned on every GET /cloud-browsers call:

Field	Meaning
`limit`	Maximum number of saved profiles your plan allows
`runningLimit`	Maximum number of simultaneously running browsers
`runningCount`	Current count of starting + running + stopping browsers

The Free plan allows saving one profile but cannot launch a browser. A paid plan is required to start a cloud browser runtime.

Opening the interactive viewer

When a cloud browser is running, the runtime.connectUrl field contains a URL you can open directly in your own browser to see and interact with the remote session in real time. This URL points to the live browser viewer and requires your profile owner’s session cookie — an API key alone does not grant viewer access.

Closing the viewer tab does not stop billing. The browser continues running — and consuming credits — until you explicitly call POST /cloud-browsers/:id/stop. Always stop the browser through the API or dashboard when you are done.

Two ways to create and start

Option 1: Create then Start

Use this approach when you want to save a profile for later or when you need fine-grained control over when the browser starts.

Create the profile

POST /cloud-browsers saves the profile configuration and returns an id. The browser is not started yet and consumes no running quota.

curl --fail-with-body -sS -X POST "https://api.adscrawl.net/cloud-browsers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remark": "work profile",
    "browserSettings": {
      "viewport": { "width": 1440, "height": 900 }
    }
  }'

Start the browser

POST /cloud-browsers/:id/start launches the saved profile. Pass your proxy on every start request — saved proxy settings do not replace the required top-level proxy field for API key callers.

curl --fail-with-body -sS -X POST \
  "https://api.adscrawl.net/cloud-browsers/BROWSER_ID/start" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy": {
      "server": "http://proxy.example.com:8080",
      "username": "proxy-user",
      "password": "proxy-password"
    }
  }'

The endpoint waits for startup confirmation and returns 200 only once the browser reaches running.

Option 2: Launch in one step

POST /cloud-browsers/launch creates the profile and starts the browser in a single request, waiting for running before returning 201. Use this when you want to open a browser immediately without a separate create step.

curl --fail-with-body -sS --max-time 200 \
  -X POST "https://api.adscrawl.net/cloud-browsers/launch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy": {
      "server": "http://proxy.example.com:8080",
      "username": "proxy-user",
      "password": "proxy-password"
    },
    "tabs": ["https://example.com"]
  }'

Each call to POST /cloud-browsers/launch creates a new profile — there is no idempotency key. If the request fails or the response is lost, inspect GET /cloud-browsers before retrying. Never automatically repeat a failed launch call without checking whether a profile was created.

Proxy requirements

Proxy rules differ depending on how you authenticate:

API key (X-API-Key)
Session / JWT Bearer

Every start request — including /launch and /start — must include a valid top-level proxy object. Saved browserSettings.proxy, a previous run’s proxy, and countryCode cannot substitute for it.

{
  "proxy": {
    "server": "http://proxy.example.com:8080",
    "username": "proxy-user",
    "password": "proxy-password"
  }
}

Dashboard and JWT Bearer callers may use either a custom proxy object or countryCode (a two-letter region code or "GLOBAL"). A session-authenticated start also requires apiKeyId for an active API key owned by the same user.

{
  "apiKeyId": "YOUR_API_KEY_ID",
  "countryCode": "GLOBAL"
}

A proxy failure must never fall back to a direct connection. If your proxy is unreachable, fix it or wait for service recovery — do not remove the proxy field to work around the error.

Credit billing

Cloud browsers are billed at 1 credit per started minute, rounded up, from the moment the browser successfully reaches running until stop is confirmed. A 202 stopping response means shutdown is still in progress — credits continue until runtime.status is stopped. Poll GET /cloud-browsers/:id with a bounded retry loop to confirm the stop. Calling stop multiple times does not charge twice; repeated stops on an already-stopped profile return 200 with runtime.status: "stopped" at no cost.

API reference

List Cloud Browsers

List saved profiles and read your saved and running quotas.

Create Profile

Save a new browser profile without starting a runtime.

Launch

Create and start a browser in one request, waiting for running.

Start

Start a previously saved profile and wait for running confirmation.

Stop

Stop a running browser and release its running quota slot.

Get Started

Core Concepts

Guides

Pricing & Limits

Cloud Browsers: Persistent, Reusable Browser Profiles

Lifecycle states

Saved profiles vs. running sessions

Opening the interactive viewer

Two ways to create and start

Option 1: Create then Start

Option 2: Launch in one step

Proxy requirements

Credit billing

API reference

List Cloud Browsers

Create Profile

Launch

Start

Stop

​Lifecycle states

​Saved profiles vs. running sessions

​Opening the interactive viewer

​Two ways to create and start

​Option 1: Create then Start

​Option 2: Launch in one step

​Proxy requirements

​Credit billing

​API reference

List Cloud Browsers

Create Profile

Launch

Start

Stop

Lifecycle states

Saved profiles vs. running sessions

Opening the interactive viewer

Two ways to create and start

Option 1: Create then Start

Option 2: Launch in one step

Proxy requirements

Credit billing

API reference