cdpfleet Docs GitHub Dashboard

Examples

Every example is a complete program. Set CDPFLEET_API_KEY, replace the placeholder proxy with yours, install the client named at the top, and run it.

Google Chrome, beta channel

Run the next Chrome release before it ships. Use "dev" for the dev channel.

// npm install [email protected]
// Browsers run on cdpfleet, so no `npx playwright install` is needed.
import { chromium } from 'playwright';

const KEY = process.env.CDPFLEET_API_KEY;

// 1. Launch the browser
const res = await fetch('https://starter.cdpfleet.com/chrome/session', {
  method: 'POST',
  headers: { 'x-api-key': KEY, 'content-type': 'application/json' },
  body: JSON.stringify({
    proxy: 'http://user:[email protected]:8080',
    channel: 'beta',
    headless: 'new',
  }),
});
if (!res.ok) throw new Error(`launch failed: ${res.status} ${await res.text()}`);
const { wsUrl } = await res.json();

// 2. Connect and drive it
const browser = await chromium.connect(wsUrl, { headers: { 'x-api-key': KEY } });
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close(); // ends the session and stops billing

Pin an older Chrome major (153)

Run a previous major to reproduce or compare behaviour. Previous majors rotate as new versions ship, so check the Chrome page for the current list rather than hard-coding one.

// npm install [email protected]
// Browsers run on cdpfleet, so no `npx playwright install` is needed.
import { chromium } from 'playwright';

const KEY = process.env.CDPFLEET_API_KEY;

// 1. Launch the browser
const res = await fetch('https://starter.cdpfleet.com/chrome/session', {
  method: 'POST',
  headers: { 'x-api-key': KEY, 'content-type': 'application/json' },
  body: JSON.stringify({
    proxy: 'http://user:[email protected]:8080',
    version: '153',
    headless: 'new',
  }),
});
if (!res.ok) throw new Error(`launch failed: ${res.status} ${await res.text()}`);
const { wsUrl } = await res.json();

// 2. Connect and drive it
const browser = await chromium.connect(wsUrl, { headers: { 'x-api-key': KEY } });
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close(); // ends the session and stops billing

Camoufox with a Windows fingerprint

Camoufox builds a consistent identity at launch. Here: Windows, US English, human-like mouse movement, WebRTC disabled. Replace the proxy with yours; Camoufox also matches its location to it.

// npm install [email protected]
// Browsers run on cdpfleet, so no `npx playwright install` is needed.
import { firefox } from 'playwright';

const KEY = process.env.CDPFLEET_API_KEY;

// 1. Launch the browser
const res = await fetch('https://starter.cdpfleet.com/camoufox/session', {
  method: 'POST',
  headers: { 'x-api-key': KEY, 'content-type': 'application/json' },
  body: JSON.stringify({
    proxy: 'http://user:[email protected]:8080',
    os: 'windows',
    locale: 'en-US',
    humanize: true,
    block_webrtc: true,
  }),
});
if (!res.ok) throw new Error(`launch failed: ${res.status} ${await res.text()}`);
const { wsUrl } = await res.json();

// 2. Connect and drive it
const browser = await firefox.connect(wsUrl, { headers: { 'x-api-key': KEY } });
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close(); // ends the session and stops billing

Proxy pool with per-host rules

Spread traffic over two residential exits and send CDN assets through a datacenter pool. See Proxies.

// npm install [email protected]
// Browsers run on cdpfleet, so no `npx playwright install` is needed.
import { chromium } from 'playwright';

const KEY = process.env.CDPFLEET_API_KEY;

// 1. Launch the browser
const res = await fetch('https://starter.cdpfleet.com/chromium/session', {
  method: 'POST',
  headers: { 'x-api-key': KEY, 'content-type': 'application/json' },
  body: JSON.stringify({
    headless: 'new',
    proxy: [
      'http://u:[email protected]:8080',
      'http://u:[email protected]:8080',
    ],
    proxy_rules: [
      {
        hosts: [
          '*.cloudfront.net',
        ],
        proxy: 'http://u:[email protected]:4444',
      },
    ],
  }),
});
if (!res.ok) throw new Error(`launch failed: ${res.status} ${await res.text()}`);
const { wsUrl } = await res.json();

// 2. Connect and drive it
const browser = await chromium.connect(wsUrl, { headers: { 'x-api-key': KEY } });
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close(); // ends the session and stops billing

Long-running session

Keep a session alive for up to two hours and tolerate five idle minutes. Both are capped by your plan.

// npm install [email protected]
// Browsers run on cdpfleet, so no `npx playwright install` is needed.
import { firefox } from 'playwright';

const KEY = process.env.CDPFLEET_API_KEY;

// 1. Launch the browser
const res = await fetch('https://starter.cdpfleet.com/firefox/session', {
  method: 'POST',
  headers: { 'x-api-key': KEY, 'content-type': 'application/json' },
  body: JSON.stringify({
    proxy: 'http://user:[email protected]:8080',
    headless: true,
    overall_timeout: '2h',
    inactivity_timeout: '5m',
  }),
});
if (!res.ok) throw new Error(`launch failed: ${res.status} ${await res.text()}`);
const { wsUrl } = await res.json();

// 2. Connect and drive it
const browser = await firefox.connect(wsUrl, { headers: { 'x-api-key': KEY } });
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close(); // ends the session and stops billing

Mobile device emulation

Emulate a phone client-side with Playwright's device descriptors after connecting. It works on Chromium-family browsers (Android) and WebKit (iPhone); Firefox and Camoufox don't support mobile emulation.

import { webkit, devices } from 'playwright';
// …launch /webkit/session as in the Quickstart, then:
const browser = await webkit.connect(wsUrl, { headers: { 'x-api-key': KEY } });
const context = await browser.newContext({ ...devices['iPhone 15'] });
const page = await context.newPage();
await page.goto('https://example.com');
from playwright.sync_api import sync_playwright
# …launch /chromium/session as in the Quickstart, then:
with sync_playwright() as p:
    browser = p.chromium.connect(ws_url, headers={"x-api-key": KEY})
    context = browser.new_context(**p.devices["Pixel 7"])
    page = context.new_page()
    page.goto("https://example.com")

Handling busy and limit responses

Retry 503 with backoff — the fleet was momentarily full. Respect Retry-After on 429; retrying earlier can't succeed. Never retry 4xx other than 429 — the request itself needs fixing. See Errors & limits.

async function launch(engine, body, attempts = 5) {
  for (let i = 0; ; i++) {
    const res = await fetch(`https://starter.cdpfleet.com/${engine}/session`, {
      method: 'POST',
      headers: { 'x-api-key': KEY, 'content-type': 'application/json' },
      body: JSON.stringify(body),
    });
    if (res.ok) return res.json();
    const retryable = res.status === 503 || res.status === 429;
    if (!retryable || i + 1 >= attempts) throw new Error(`launch failed: ${res.status} ${await res.text()}`);
    const after = Number(res.headers.get('retry-after')) || 2 ** i;
    await new Promise((r) => setTimeout(r, Math.min(after, 60) * 1000));
  }
}