Cloud browsers

Request

Responses

200

application/jsonlimit is the plan's saved-profile allowance; runningLimit is the user's concurrent running allowance; runningCount includes starting, running, and stopping across all of the user's profiles, pages, API keys, and dashboard sessions, excluding temporary /cdp/sessions. users.cloud_browser_running_limit defaults to 1 for NULL or negative values; 0 blocks new starts and a positive value sets the cap. List and each start read it live; lowering it does not stop existing instances. Global capacity still applies, without the temporary CDP per-key concurrency limit.

200

application/jsonruntime.status is starting, running, stopping, or stopped; starting/stopping still reserve quota. runtimeKind is neko or worker_cdp. Active sessions include sessionId and expiresAt. Only running may include connectUrl: open it directly for the instance's interactive browser, signed in as the profile owner. neko points to /cloud-browser-runtime/{sessionId}/ on the API origin and omits cdpBaseUrl. Fixed usr/pwd parameters are public viewer protocol values; authorization still uses the session cookie, without read-only cast mode. worker_cdp uses CDP Studio and may return cdpBaseUrl with a temporary token. Use returned URLs; never construct them or add API keys, cookies, or proxy credentials. If a URL is absent, query the actual status first.

401

application/jsonAuthentication is missing, invalid, or expired.

503

application/jsonCDP_WORKER_UNAVAILABLE, or Cloud browser runtime is unavailable without a code. A missing original node, changed bootId, or temporary loss of contact does not confirm a stop; the session and quota remain reserved and connection URLs may be omitted.

500

application/jsonInternal error: an internal service failure.

Request examples

curl --fail-with-body --silent --show-error --max-time 65 \
  -X GET 'https://api.adscrawl.net/cloud-browsers?page=1&pageSize=10' \
  -H 'x-api-key: <api-key>'

Response examples

{
  "ok": true,
  "data": [
    {
      "id": "<browser-id>",
      "source": "manual",
      "deleteOnStop": false,
      "remark": "work profile",
      "browserSettings": {
        "viewport": {
          "width": 1440,
          "height": 900
        }
      },
      "proxyDisplayIp": null,
      "proxyDisplayRegion": null,
      "lastOpenedAt": null,
      "updatedAt": "2026-09-07T08:00:00.000Z",
      "runtime": {
        "runtimeKind": "neko",
        "status": "stopped"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "totalPages": 1
  },
  "limit": 10,
  "runningLimit": 1,
  "runningCount": 0
}

Request

Responses

201

application/jsonReturns {ok: true, id}; the profile is stopped and consumes no running quota. Free plans allow one saved profile; see list.limit for the current allowance. The Node.js request example contains the complete lifecycle.

400

application/jsonEmpty body, null, arrays, scalars, invalid field types, an oversized remark, Invalid cookies, INVALID_PROXY, INVALID_COUNTRY_CODE, or COUNTRY_PROXY_CONFLICT. {} is a valid create request.

401

application/jsonAuthentication is missing, invalid, or expired.

409

application/jsonCloud Browser limit reached: the saved-profile limit is reached, without a code. This differs from running quota errors.

500

application/jsonInternal error: an internal service failure.

Request examples

curl --fail-with-body --silent --show-error --max-time 65 \
  -X POST 'https://api.adscrawl.net/cloud-browsers' \
  -H 'x-api-key: <api-key>' \
  -H 'content-type: application/json' \
  --data '{
  "remark": "work profile",
  "browserSettings": {
    "viewport": {
      "width": 1440,
      "height": 900
    }
  }
}'

{
  "remark": "work profile",
  "browserSettings": {
    "viewport": {
      "width": 1440,
      "height": 900
    }
  }
}

// Node.js 20+, save as .mjs. Replace proxy placeholders before running.
const baseUrl = "https://api.adscrawl.net";
const apiKey = process.env.ADSCRAWL_API_KEY;
if (!apiKey) throw new Error("ADSCRAWL_API_KEY is required");
const proxy = {
  "server": "http://proxy.example.com:8080",
  "username": "<proxy-user>",
  "password": "<proxy-password>"
};

async function request(method, path, body, timeoutMs = 65000) {
  const res = await fetch(baseUrl + path, {
    method,
    headers: { "x-api-key": apiKey, "content-type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(timeoutMs),
  });
  const data = await res.json();
  if (!res.ok) {
    const error = new Error(data.error || "HTTP " + res.status);
    error.status = res.status;
    error.code = data.code;
    error.id = data.id;
    throw error;
  }
  return data;
}

async function stopAndWait(id) {
  const path = "/cloud-browsers/" + encodeURIComponent(id);
  // At most 30 attempts, 2 seconds apart; each request times out after 10 seconds.
  for (let attempt = 0; attempt < 30; attempt++) {
    try {
      const stopped = await request("POST", path + "/stop", undefined, 10000);
      if (stopped.runtime.status === "stopped") return;
      const current = await request("GET", path, undefined, 10000);
      if (current.runtime.status === "stopped") return;
    } catch (error) {
      if (error.code !== "CDP_SESSION_STARTING" &&
          !(error.status >= 500) && error.name !== "TimeoutError") throw error;
    }
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
  throw new Error("Stop unconfirmed; quota is still reserved. Retry stop for " + id);
}
const { id } = await request("POST", "/cloud-browsers", {
  "remark": "work profile",
  "browserSettings": {
    "viewport": {
      "width": 1440,
      "height": 900
    }
  }
});
try {
  // Include a valid proxy again on EVERY start, even for an existing profile.
  await request("POST", "/cloud-browsers/" + encodeURIComponent(id) + "/start", { proxy });
  const current = await request("GET", "/cloud-browsers/" + encodeURIComponent(id));
  console.log({ id, source: current.source, status: current.runtime.status, connectUrl: current.runtime.connectUrl });
  // Open connectUrl in a browser signed in as the profile owner before continuing.
  const { limit, runningLimit, runningCount } = await request("GET", "/cloud-browsers");
  console.log({ limit, runningLimit, runningCount });
} finally {
  // Also attempt cleanup after a failed start: a runtime may still need recovery.
  await stopAndWait(id);
}
console.log("Stopped; the saved profile remains", id);

Response examples

{
  "ok": true,
  "id": "<browser-id>"
}

Request

Responses

201

application/jsonReturns {ok: true, id, source: launch, deleteOnStop: false, runtime} and Location: /cloud-browsers/<id> only after running is confirmed. runtime.connectUrl opens the interactive browser directly; Location is the query endpoint. source only identifies origin. Manual stop, expiry, and confirmed cleanup of failed startup retain settings and cookie/tab snapshots. The profile still counts toward saved allowance and can be queried, restarted, or explicitly deleted. Closing the viewer does not stop the browser.

201

application/jsonruntime.status is starting, running, stopping, or stopped; starting/stopping still reserve quota. runtimeKind is neko or worker_cdp. Active sessions include sessionId and expiresAt. Only running may include connectUrl: open it directly for the instance's interactive browser, signed in as the profile owner. neko points to /cloud-browser-runtime/{sessionId}/ on the API origin and omits cdpBaseUrl. Fixed usr/pwd parameters are public viewer protocol values; authorization still uses the session cookie, without read-only cast mode. worker_cdp uses CDP Studio and may return cdpBaseUrl with a temporary token. Use returned URLs; never construct them or add API keys, cookies, or proxy credentials. If a URL is absent, query the actual status first.

201

application/jsonUses the existing paid-plan, saved limit, user runningLimit, and global capacity rules. starting/running/stopping reserve running allowance. Billing is one credit per started minute from successful start to confirmed stop. Confirmed stopped releases running allowance; saved count stays unchanged until explicit DELETE /cloud-browsers/{id}. Requires Cloud Runtime to be enabled.

400

application/jsonPROXY_REQUIRED, INVALID_PROXY, INVALID_TABS, INVALID_COOKIES, INVALID_FINGERPRINT_SETTINGS. Explicit null, unknown fields (including countryCode/source/browserSettings), invalid JSON, and incorrect types are rejected before profile creation.

401

application/jsonAuthentication is missing, invalid, or expired.

402

application/jsonPAID_PLAN_REQUIRED or INSUFFICIENT_CREDITS; no profile is created.

403

application/jsonThe selected key belongs to another user or differs from the authenticated key; no profile is created.

409

application/jsonCloud Browser limit reached: saved allowance full, no creation. CLOUD_BROWSER_CONCURRENCY_LIMIT: running allowance full or zero. If a profile was created, the response includes id, source: launch, deleteOnStop: false, deleted: false, and the actual runtime; the profile remains saved.

502/503/504/500

application/jsonUses start errors and capacity retry metadata. Errors after profile creation include id, runtime, and Location, plus sessionId once reserved. Unconfirmed cleanup remains stopping and reserves quota. Disabled Cloud Runtime returns 503 without Worker dispatch. Startup waits up to 60 seconds; cleanup confirmation may take up to 120 more seconds.

502/503/504/500

application/jsonEach call creates a new profile without an idempotency key; never automatically repeat launch. On an error with id, inspect it and retry the same stop with a bound until stopped. The profile remains with deleted: false; unconfirmed cleanup also reserves running allowance. If the response is lost, inspect the list and quota first; do not assume nothing was created or that it stopped.

Request examples

curl --fail-with-body --silent --show-error --max-time 200 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/launch' \
  -H 'x-api-key: <api-key>' \
  -H 'content-type: application/json' \
  --data '{
  "proxy": {
    "server": "http://proxy.example.com:8080",
    "username": "<proxy-user>",
    "password": "<proxy-password>"
  },
  "tabs": [
    "https://example.com"
  ],
  "cookies": [
    {
      "name": "sid",
      "value": "<cookie-value>",
      "domain": "example.com",
      "path": "/",
      "secure": true
    }
  ],
  "fingerprint": {
    "canvas": "real"
  }
}'

{
  "proxy": {
    "server": "http://proxy.example.com:8080",
    "username": "<proxy-user>",
    "password": "<proxy-password>"
  },
  "tabs": [
    "https://example.com"
  ],
  "cookies": [
    {
      "name": "sid",
      "value": "<cookie-value>",
      "domain": "example.com",
      "path": "/",
      "secure": true
    }
  ],
  "fingerprint": {
    "canvas": "real"
  }
}

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

// Node.js 20+, save as .mjs. Replace proxy placeholders before running.
const baseUrl = "https://api.adscrawl.net";
const apiKey = process.env.ADSCRAWL_API_KEY;
if (!apiKey) throw new Error("ADSCRAWL_API_KEY is required");
const proxy = {
  "server": "http://proxy.example.com:8080",
  "username": "<proxy-user>",
  "password": "<proxy-password>"
};

async function request(method, path, body, timeoutMs = 65000) {
  const res = await fetch(baseUrl + path, {
    method,
    headers: { "x-api-key": apiKey, "content-type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(timeoutMs),
  });
  const data = await res.json();
  if (!res.ok) {
    const error = new Error(data.error || "HTTP " + res.status);
    error.status = res.status;
    error.code = data.code;
    error.id = data.id;
    throw error;
  }
  return data;
}

async function stopAndWait(id) {
  const path = "/cloud-browsers/" + encodeURIComponent(id);
  // At most 30 attempts, 2 seconds apart; each request times out after 10 seconds.
  for (let attempt = 0; attempt < 30; attempt++) {
    try {
      const stopped = await request("POST", path + "/stop", undefined, 10000);
      if (stopped.runtime.status === "stopped") return;
      const current = await request("GET", path, undefined, 10000);
      if (current.runtime.status === "stopped") return;
    } catch (error) {
      if (error.code !== "CDP_SESSION_STARTING" &&
          !(error.status >= 500) && error.name !== "TimeoutError") throw error;
    }
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
  throw new Error("Stop unconfirmed; quota is still reserved. Retry stop for " + id);
}
let id;
try {
  // One call creates AND starts. Never automatically repeat this POST.
  const launched = await request("POST", "/cloud-browsers/launch", {
    proxy,
    tabs: ["https://example.com"],
    // cookies and fingerprint omitted: use their defaults.
  }, 195000);
  id = launched.id;
  const current = await request("GET", "/cloud-browsers/" + encodeURIComponent(id));
  console.log({ id, status: current.runtime.status });
} catch (error) {
  id = id || error.id;
  if (!id) console.error("No profile id received; inspect /cloud-browsers before retrying launch.");
  throw error;
} finally {
  // Errors after profile creation also return id; unconfirmed cleanup reserves quota.
  if (id) await stopAndWait(id);
}
console.log("Stopped; the saved profile remains", id);

Response examples

{
  "ok": true,
  "id": "<browser-id>",
  "source": "launch",
  "deleteOnStop": false,
  "runtime": {
    "runtimeKind": "neko",
    "status": "running",
    "sessionId": "<session-id>",
    "expiresAt": "2026-09-07T09:00:00.000Z",
    "connectUrl": "https://api.adscrawl.net/cloud-browser-runtime/<session-id>/?usr=adscrawl&pwd=adscrawl"
  }
}

{
  "error": "Cloud browser runtime request timed out",
  "code": "CLOUD_RUNTIME_TIMEOUT",
  "id": "<browser-id>",
  "source": "launch",
  "deleteOnStop": false,
  "deleted": false,
  "runtime": {
    "runtimeKind": "neko",
    "status": "stopping",
    "sessionId": "<session-id>",
    "expiresAt": "2026-09-07T09:00:00.000Z"
  }
}

Request

Responses

200

application/jsonReturns the profile directly, without a data or ok wrapper: id, remark, browserSettings, nullable proxyDisplayIp/Region and lastOpenedAt, updatedAt, and runtime. Proxy credentials are removed from responses; the owner can read saved cookies.

200

application/jsonruntime.status is starting, running, stopping, or stopped; starting/stopping still reserve quota. runtimeKind is neko or worker_cdp. Active sessions include sessionId and expiresAt. Only running may include connectUrl: open it directly for the instance's interactive browser, signed in as the profile owner. neko points to /cloud-browser-runtime/{sessionId}/ on the API origin and omits cdpBaseUrl. Fixed usr/pwd parameters are public viewer protocol values; authorization still uses the session cookie, without read-only cast mode. worker_cdp uses CDP Studio and may return cdpBaseUrl with a temporary token. Use returned URLs; never construct them or add API keys, cookies, or proxy credentials. If a URL is absent, query the actual status first.

200

application/jsonsource is manual or launch; launch identifies the create-and-launch API, not a deletion policy. The backend handles legacy deleteOnStop flags and now returns false. Stop preserves configuration, snapshots, and source, still counting toward saved allowance. Previously deleted records are not restored and may return deleted: true, stopped, and empty settings; only actually deleted records disappear from the list.

401

application/jsonAuthentication is missing, invalid, or expired.

404

application/jsonThe profile does not exist or belongs to another user.

503

application/jsonCDP_WORKER_UNAVAILABLE, or Cloud browser runtime is unavailable without a code. A missing original node, changed bootId, or temporary loss of contact does not confirm a stop; the session and quota remain reserved and connection URLs may be omitted.

500

application/jsonInternal error: an internal service failure.

Request examples

curl --fail-with-body --silent --show-error --max-time 65 \
  -X GET 'https://api.adscrawl.net/cloud-browsers/<browser-id>' \
  -H 'x-api-key: <api-key>'

Response examples

{
  "id": "<browser-id>",
  "source": "manual",
  "deleteOnStop": false,
  "remark": "work profile",
  "browserSettings": {
    "viewport": {
      "width": 1440,
      "height": 900
    }
  },
  "proxyDisplayIp": null,
  "proxyDisplayRegion": null,
  "lastOpenedAt": null,
  "updatedAt": "2026-09-07T08:00:00.000Z",
  "runtime": {
    "runtimeKind": "neko",
    "status": "stopped"
  }
}

{
  "id": "<browser-id>",
  "source": "manual",
  "deleteOnStop": false,
  "remark": "work profile",
  "browserSettings": {
    "viewport": {
      "width": 1440,
      "height": 900
    }
  },
  "proxyDisplayIp": null,
  "proxyDisplayRegion": null,
  "lastOpenedAt": null,
  "updatedAt": "2026-09-07T08:00:00.000Z",
  "runtime": {
    "runtimeKind": "neko",
    "status": "stopping",
    "sessionId": "<session-id>",
    "expiresAt": "2026-09-07T09:00:00.000Z"
  }
}

{
  "id": "<browser-id>",
  "source": "launch",
  "deleteOnStop": false,
  "remark": "work profile",
  "browserSettings": {
    "viewport": {
      "width": 1440,
      "height": 900
    }
  },
  "proxyDisplayIp": null,
  "proxyDisplayRegion": null,
  "lastOpenedAt": null,
  "updatedAt": "2026-09-07T08:00:00.000Z",
  "runtime": {
    "runtimeKind": "neko",
    "status": "stopped"
  }
}

Request

Responses

200

application/jsonWaits for startup confirmation and returns {ok: true, runtime} only at running, never a successful starting state. Requires an active paid plan. Billing runs from successful start to stop at one credit per started minute, rounded up. See get for runtime fields; neko omits cdpBaseUrl.

400

application/jsonPROXY_REQUIRED for a missing top-level proxy; INVALID_PROXY for an invalid proxy; COUNTRY_PROXY_CONFLICT for proxy and countryCode together; INVALID_COUNTRY_CODE, INVALID_FINGERPRINT_SETTINGS, or Invalid cookies. Invalid body/cookies/fingerprint types, missing dashboard apiKeyId, or a missing/inactive/expired selected key also return 400.

401

application/jsonAuthentication is missing, invalid, or expired.

402

application/jsonPAID_PLAN_REQUIRED: no active paid plan. INSUFFICIENT_CREDITS: less than one credit available (includes balance and requiredCredits).

403

application/jsonapiKeyId differs from the authenticated key, or the selected key belongs to another user.

404

application/jsonThe profile does not exist or belongs to another user.

409

application/jsonCLOUD_BROWSER_CONCURRENCY_LIMIT: the user allowance is full or zero. Browser is already running (without a code): this profile has an active session. limit is the plan's saved-profile allowance; runningLimit is the user's concurrent running allowance; runningCount includes starting, running, and stopping across all of the user's profiles, pages, API keys, and dashboard sessions, excluding temporary /cdp/sessions. users.cloud_browser_running_limit defaults to 1 for NULL or negative values; 0 blocks new starts and a positive value sets the cap. List and each start read it live; lowering it does not stop existing instances. Global capacity still applies, without the temporary CDP per-key concurrency limit.

502

application/jsonCLOUD_RUNTIME_AUTH_FAILED, CLOUD_RUNTIME_NOT_FOUND, CLOUD_RUNTIME_HTTP_ERROR, CLOUD_RUNTIME_INVALID_RESPONSE, or CLOUD_RUNTIME_CONTROLLER_FAILED: runtime rejection or invalid response.

503

application/jsonCLUSTER_NO_CAPACITY: online nodes are full, with nullable nextAvailableAt and retryAfterMs. CDP session capacity exhausted (without a code): global capacity is full. Other codes include DYNAMIC_PROXY_NOT_CONFIGURED, MANAGED_PROXY_UNAVAILABLE, CLOUD_RUNTIME_CONFIG_INVALID, and CLOUD_RUNTIME_UNREACHABLE. Proxy failure never connects directly; inspect the profile before retrying.

503

application/jsonCDP_WORKER_UNAVAILABLE, or Cloud browser runtime is unavailable without a code. A missing original node, changed bootId, or temporary loss of contact does not confirm a stop; the session and quota remain reserved and connection URLs may be omitted.

504

application/jsonCLOUD_RUNTIME_TIMEOUT: startup timeout does not prove the runtime is absent. Inspect its status and retry stop when needed; stopping and quota remain until cleanup is confirmed.

500

application/jsonInternal error: an internal service failure.

Request examples

curl --fail-with-body --silent --show-error --max-time 65 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/<browser-id>/start' \
  -H 'x-api-key: <api-key>' \
  -H 'content-type: application/json' \
  --data '{
  "proxy": {
    "server": "http://proxy.example.com:8080",
    "username": "<proxy-user>",
    "password": "<proxy-password>"
  }
}'

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

{
  "proxy": {
    "protocol": "socks5",
    "host": "proxy.example.com",
    "port": 1080,
    "username": "<proxy-user>",
    "password": "<proxy-password>"
  }
}

curl --fail-with-body --silent --show-error --max-time 65 \
  'https://api.adscrawl.net/cloud-browsers/<browser-id>/start' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'content-type: application/json' \
  --data '{
  "apiKeyId": "<api-key-id>",
  "countryCode": "GLOBAL"
}'

Response examples

{
  "ok": true,
  "runtime": {
    "runtimeKind": "neko",
    "status": "running",
    "sessionId": "<session-id>",
    "expiresAt": "2026-09-07T09:00:00.000Z",
    "connectUrl": "https://api.adscrawl.net/cloud-browser-runtime/<session-id>/?usr=adscrawl&pwd=adscrawl"
  }
}

{
  "error": "API key starts require an explicit proxy in every request",
  "code": "PROXY_REQUIRED"
}

{
  "error": "Cloud browser running limit reached",
  "code": "CLOUD_BROWSER_CONCURRENCY_LIMIT"
}

{
  "error": "Cloud browser cluster has no available capacity",
  "code": "CLUSTER_NO_CAPACITY",
  "nextAvailableAt": null,
  "retryAfterMs": null
}

Request

Responses

200

application/jsonruntime.status=stopped: stop is confirmed or no active session existed, releasing running allowance. Both manual and launch profiles retain settings, snapshots, and source and still reserve saved allowance. Profiles can restart and are removed only by explicit deletion. Repeated stop returns stopped without duplicate billing. source identifies origin and deleteOnStop is false; only previously deleted records return deleted: true. sessionId is omitted when no active session existed.

202

application/jsonruntime.status=stopping: another stop is in progress; completion is unconfirmed and quota remains reserved. Poll GET details with a bound; retry the same stop if it stays stopping, until stopped is confirmed. The create endpoint's Node.js lifecycle includes polling and retries.

401

application/jsonAuthentication is missing, invalid, or expired.

404

application/jsonThe profile does not exist or belongs to another user.

409

application/jsonCDP_SESSION_STARTING: startup is still in progress; wait and retry stop.

503

application/jsonCDP_WORKER_UNAVAILABLE, or Cloud browser runtime is unavailable without a code. A missing original node, changed bootId, or temporary loss of contact does not confirm a stop; the session and quota remain reserved and connection URLs may be omitted.

500

application/jsonInternal error: a failed or timed-out stop is not success. The session may remain stopping and reserve quota; inspect it and retry stop after reachability is restored. Losing the original node identity must not redirect deletion to a new node or justify a fabricated stopped state.

Request examples

curl --fail-with-body --silent --show-error --max-time 65 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/<browser-id>/stop' \
  -H 'x-api-key: <api-key>'

Response examples

{
  "ok": true,
  "runtime": {
    "status": "stopped",
    "sessionId": "<session-id>"
  }
}

{
  "ok": true,
  "runtime": {
    "status": "stopping",
    "sessionId": "<session-id>"
  }
}

{
  "error": "CDP session is starting; retry after startup completes",
  "code": "CDP_SESSION_STARTING"
}

{
  "error": "Cloud browser runtime is unavailable"
}

{
  "ok": true,
  "source": "launch",
  "deleteOnStop": false,
  "runtime": {
    "status": "stopped",
    "sessionId": "<session-id>"
  }
}