Skip to main content

Puppeteer Cloud Browser

Puppeteer Cloud Browser for Existing Node.js Scripts

Run your Puppeteer workflow against cloud Chromium. Your Node.js application controls navigation and extraction while AdsCrawl hosts the browser session.

01 / OVERVIEW

What is Puppeteer Cloud Browser?

AdsCrawl provides a Puppeteer cloud browser through its Remote CDP API. Create a session, discover its WebSocket debugger endpoint and use puppeteer.connect to attach your existing Node.js script to a remote Puppeteer browser workflow.

02 / USE CASES

Where it fits

01

Move browser execution off your server

Use puppeteer-core to connect without installing a local Chromium binary for this workflow. Your application still runs and coordinates the script.

02

Keep familiar page operations

Navigate, evaluate page content and capture results using Puppeteer. Review assumptions about local files, extensions and the browser version before migrating.

03

Scope each job to a session

Create a temporary session for a job and release it in a finally block. Track the session id so failures can be cleaned up.

03 / QUICKSTART

Start with one complete workflow

  1. Use a server-side API key to POST /cdp/sessions and keep sessionId and cdpBaseUrl.
  2. Request /json/version on cdpBaseUrl, preserving its token, and read webSocketDebuggerUrl.
  3. Pass that URL as browserWSEndpoint to puppeteer.connect and run your page actions.
  4. Disconnect Puppeteer and call DELETE /cdp/sessions/:sessionId in finally, including after a failed page action.

Requires Node.js with fetch support and puppeteer-core (npm install puppeteer-core). Save as an .mjs file. Set the ADSCRAWL_API_KEY environment variable on your server first.

Full request and response reference →
Puppeteer
import puppeteer from "puppeteer-core";

const base = "https://api.adscrawl.net";
const headers = {
  "x-api-key": process.env.ADSCRAWL_API_KEY,
  "content-type": "application/json",
};
const response = await fetch(base + "/cdp/sessions", {
  method: "POST", headers,
  body: JSON.stringify({ idleTimeoutMs: 600000 }),
});
if (!response.ok) throw new Error("Create session failed: HTTP " + response.status);
const session = await response.json();
if (typeof session.sessionId !== "string" || !session.sessionId) {
  throw new Error("Create response is missing sessionId");
}
try {
  if (typeof session.cdpBaseUrl !== "string" || !session.cdpBaseUrl) {
    throw new Error("Create response is missing cdpBaseUrl");
  }
  const discovery = new URL(session.cdpBaseUrl);
  discovery.pathname = discovery.pathname.replace(/\/+$/, "") + "/json/version";
  const version = await fetch(discovery);
  if (!version.ok) throw new Error("CDP discovery failed: HTTP " + version.status);
  const { webSocketDebuggerUrl } = await version.json();
  if (typeof webSocketDebuggerUrl !== "string" || !webSocketDebuggerUrl) {
    throw new Error("Discovery response is missing webSocketDebuggerUrl");
  }
  const browser = await puppeteer.connect({
    browserWSEndpoint: webSocketDebuggerUrl,
  });
  try {
    const page = await browser.newPage();
    await page.goto("https://www.adscrawl.net");
    const title = await page.title();
    // Use title in your application; keep page content and session URLs out of logs.
  } finally {
    await browser.disconnect();
  }
} finally {
  const stopped = await fetch(base + "/cdp/sessions/" + encodeURIComponent(session.sessionId), {
    method: "DELETE", headers,
  });
  if (!stopped.ok) throw new Error("Session cleanup failed: HTTP " + stopped.status);
}

04 / LIMITS & BILLING

Know the boundaries

Sign up with 500 one-time credits. Hobby is $9/month, Starter $49/month and Pro $199/month. Launching a persistent Cloud Browser requires a paid plan.

Compare plans and allowances →
  • This integration targets Chromium over CDP; it does not provide a Firefox or WebDriver BiDi session.
  • Disconnecting Puppeteer alone does not delete the remote session or end its lifecycle.
  • Session URLs contain access tokens. Keep them on the server and out of public logs.
  • Remote execution adds network latency. Timeouts and account concurrency limits still apply.

Keep API keys on the server. For HTTP 402 check your balance; for 429 reduce concurrency and retry with backoff.

05 / FAQ

Common questions

Do I use puppeteer.launch?

Use puppeteer.connect for the already running remote browser. puppeteer.launch starts a browser process in your own environment.

Do I need to download Chromium?

Not for the remote connection shown here. puppeteer-core provides the client; AdsCrawl runs Chromium.

Can I reuse a deleted session?

No. Create a new temporary session. For saved browser profiles, review Cloud Browser API separately.