API Reference

The GoUndetected API lets you manage browser profiles, folders, and folder permissions programmatically. Everything you can do with profiles and folders in the app is available over a simple REST interface.

All requests go to https://api.goundetected.io and return JSON. Every endpoint is scoped to a single organization — an API key only ever sees or changes data in the organization it belongs to.

Authenticate every request with an API key in the Authorization header as a Bearer token:

Authorization: Bearer gou_live_xxxxxxxxxxxxxxxxxxxx

Create and manage keys in the desktop app under Settings → API Keys (owner only). The full key is shown once at creation — store it securely; it can't be retrieved later. Each key is granted scopes that gate which endpoints it can call.

Scopes: profiles:read, profiles:write, folders:read, folders:write, proxies:read, sessions:read, sessions:write.

The official `@goundetected/sdk` lets you drive GoUndetected from code — manage profiles, folders and cookies, and, the headline feature, launch a profile as a live cloud browser you control with Puppeteer or Playwright. Same account, same profiles, same proxies as the desktop app — now scriptable. npm: npmjs.com/package/@goundetected/sdk

Install

npm install @goundetected/sdk puppeteer-core

You control the cloud browser over CDP, so you need a CDP client — puppeteer-core (no bundled Chromium, it just connects) or Playwright (chromium.connectOverCDP). Works in Node 18+, ships ESM + CommonJS, with TypeScript types included.

Get an API key

In the desktop app go to Settings → API Keys and create a key with the scopes you need. For automation you almost always want profiles:read + sessions:write (add profiles:write to also create profiles from code). Treat the key like a password — put it in an env var, never in git.

Quick start

import { Goundetected } from "@goundetected/sdk";
import puppeteer from "puppeteer-core";

const gg = new Goundetected({ apiKey: process.env.GOU_API_KEY });

// 1. launch a profile as a cloud browser
const session = await gg.launch("<profileId>");

// 2. connect Puppeteer over CDP
const browser = await puppeteer.connect({ browserWSEndpoint: session.browserWSEndpoint });
const page = (await browser.pages())[0] ?? (await browser.newPage());

// 3. drive it — you're on the profile's fingerprint + proxy
await page.goto("https://ipinfo.io/json", { waitUntil: "domcontentloaded" });
console.log(await page.evaluate(() => document.body.innerText));

// 4. always stop when done (frees the browser + syncs the profile)
await browser.disconnect();
await session.stop();

That's the whole loop: launch → connect → drive → stop.

The client

const gg = new Goundetected({
  apiKey: "gou_live_…",                    // required
  baseUrl: "https://api.goundetected.io",  // optional (this is the default)
});

It exposes three resource groups plus launch(): gg.profiles (list / get / create / update / delete + cookies), gg.folders (list / get / create / update / delete), gg.sessions (list / get / heartbeat / stop), and gg.launch(profileId, opts?) which starts a cloud browser and returns a Session.

Launching a cloud browser

const session = await gg.launch(profileId, {
  region: "us-east-1",     // optional — omit to let the server pick
  ttlSeconds: 900,          // optional — auto-stop horizon (see below)
  readyTimeoutMs: 120000,   // optional — wait for the browser (default 120s)
});

launch() resolves once the browser is connectable and returns a Session: pass session.browserWSEndpoint to puppeteer.connect({ browserWSEndpoint }) or chromium.connectOverCDP(url). It also carries session.sessionId, session.region, session.heartbeat() and session.stop(). Cold start is ~30–60s — a fresh browser is provisioned on demand.

TTL, heartbeat & auto-stop

Every cloud session has an auto-stop horizon. A background reaper stops any session whose horizon lapses, so a crashed or forgotten script can't leave a browser — and your bill — running forever. Default TTL is 5 minutes: untouched for ~5 min → stopped. Each session.heartbeat() pushes the horizon 5 minutes into the future. Prefer a fixed window instead? Pass ttlSeconds at launch (60–43200, up to 12h).

For anything longer than a few minutes, heartbeat on a timer:

const hb = setInterval(() => session.heartbeat().catch(() => {}), 2 * 60 * 1000);
try {
  // … your long automation …
} finally {
  clearInterval(hb);
  await browser.disconnect();
  await session.stop();
}

Rule of thumb: heartbeat every 2 minutes while working, and stop the moment you finish — prompt stops are what keep your cloud-hours low.

Concurrency & cloud-hours limits

Cloud sessions use real compute, so every plan includes a monthly cloud-hours pool and a cap on simultaneous sessions. launch() throws before starting anything if you're over a limit — 403 for cloud-hours reached / not on your plan, 409 for concurrency. Local desktop launches are free and never counted. Watch usage in the app under Billing → Cloud browser usage.

Requirements & gotchas

Logged-in profiles — for sites behind a login (LinkedIn, etc.) the profile must already be signed in: do it once in the desktop app (cookies persist) or import them with setCookies. Heavy SPAs load async — after page.goto, await page.waitForSelector(...) for the element you need, don't rely on domcontentloaded alone. Cold starts (~30–60s) are normal (on-demand provisioning). Acceptable use — proxies + cloud are for managing your own or clients' social-media accounts; no scraping, spam, or abuse.

A profile is an isolated browser identity (fingerprint, viewport, and optional proxy). Profiles live inside folders — a new profile is placed in a folder at creation via folderId.

Read and write a profile's cookies without launching the browser. Cookies use the common Cookie-Editor / EditThisCookie JSON shape, so exports from those extensions import directly.

The profile must not be running while you import or clear its cookies — mutating a live profile returns 409 Conflict.

Folders group profiles and are the unit of access control. Deleting a folder removes its profile assignments and permissions; the profiles themselves are kept.

Control which members of your organization can view, run, or edit a folder. Permissions are per-member.

Errors return a consistent shape with the right HTTP status:

{ "error": { "code": "unauthorized", "message": "Invalid API key" } }