TypeScript SDK Reference

addReaction(match: Locator, opts: ReactionOpts | undefined): string

Registers a one-shot "reaction": a background poller (one shared loop per page) watches for the match locator and, as soon as it matches, clicks it with the full smart-click machinery (scroll, human path, occlusion gate, evade) — then removes itself. The poller yields to any in-flight input action and only fires while the pointer is idle, so a reaction naturally slots into the gaps of a retrying foreground action (e.g. it dismisses a newsletter modal blocking a CloudBrowser.click, after which the click's own retry succeeds). Reactions are scoped to the page and torn down automatically when the page/session ends.

// Auto-dismiss a consent button whenever it appears, in any frame.
const id = await browser.addReaction(css("button#accept").inAllFrames());

// Watch for a newsletter modal, but click its close "X" instead.
const id = await browser.addReaction(css("#newsletter-modal"), {
on: css(".modal-close"),
});

clearCookies(): void

Deletes every cookie in the browser context.

await browser.clearCookies();

clearStorage(origin: string | undefined): void

Deletes localStorage in the browser context.

// Wipe one origin.
await browser.clearStorage("https://example.com");

// Wipe everything.
await browser.clearStorage();

click(target: Locator, opts: ClickOpts | undefined): ElementResult

Triggers a single left mouse click on the given target.

try {
await browser.click(css("button.submit"));
} catch (e) {
if (e instanceof ClickError) console.log(e.code, e.occluder?.tagName);
}

// Right double-click on a context menu trigger.
await browser.click(css("li.menu"), { button: "right", clickCount: 2 });

dragBy(target: Locator, offsetX: number, offsetY: number): DragResult

Picks up the target and drops it at an offset relative to the pickup point.

await browser.dragBy(css(".slider .handle"), 120, 0);

dragTo(target: Locator, absoluteX: number, absoluteY: number): DragResult

Picks up the target and drops it at absolute root-viewport coordinates.

await browser.dragTo(css(".card"), 800, 400);

evaluate(expression: string): EvaluateResult<T>

Runs a JavaScript expression in the page's main frame.

const res = await browser.evaluate<string>("document.title");
console.log(res.value);

evaluateInFrame(frameId: string, expression: string): EvaluateResult<T>

Runs a JavaScript expression in the given frame.

const pages = await browser.getPages();
const iframeId = pages[0].frameTree.children[0].frameId;
await browser.evaluateInFrame(iframeId, "location.href");

fill(target: Locator, text: string, opts: FillOpts | undefined): ElementResult

Clicks the target and types text into it, appending to any existing content.

await browser.fill(css("input[name=email]"), "user@example.com");

// Wipe the field first, then type fresh content.
await browser.fill(css("input[name=email]"), "user@example.com", { clearFirst: true });

getApiKey(): string

Returns the API key used to rent this session.

getAuthSession(): AuthSession | undefined

Exports the signed-in primary account and DBSC sessions of this browser context.

const auth = await browser.getAuthSession();
if (auth) await fs.writeFile("auth.json", JSON.stringify(auth));

getCookies(): CookieParam[]

Returns all cookies currently stored in this session's browser context.

const cookies = await browser.getCookies();
for (const c of cookies) console.log(c.name, "=", c.value);

getDOM(frameId: string, opts: GetDOMOpts | undefined): DOMResult

Returns the DOM in CDP DOM.Node shape for the requested frame.

const { dom } = await browser.getDOM();

getDOMHash(frameId: string): string

Returns sha256:8 of the full-tree DOM JSON for cheap polling-based change detection.

const hash = await browser.getDOMHash();
if (hash !== lastHash) {
// DOM changed → re-fetch
}

getFingerprint(): string

Returns the browser fingerprint id in use for this session.

getObservation(opts: GetObservationOpts | undefined): string

Returns a compact, frame-aware view of the visible page — the first thing to reach for on an unfamiliar page, and the cheapest way to re-read the current state afterwards.

const obs = await browser.getObservation();
console.log(obs);

getPages(): PageInfo[]

Returns all open pages (tabs and popups) for this session's browser context.

const pages = await browser.getPages();
for (const p of pages) console.log(p.url, p.title);

getSelection(): string

Returns the current text selection.

const sel = await browser.getSelection();
console.log("user selected:", sel);

getSessionId(): string

Returns the unique server-assigned id for this browser session.

getStorage(origin: string | undefined): StorageOriginEntry[]

Returns the localStorage contents of this session's browser context, grouped by origin.

const storage = await browser.getStorage();
for (const e of storage) {
for (const { key, value } of e.items) console.log(e.origin, key, "=", value);
}

getStreamConfig(): IceServer[]

Returns the ICE servers (TURN URL + short-lived credentials) to put in your RTCPeerConnection BEFORE creating the offer, so it can gather relay candidates.

const ice = await browser.getStreamConfig();
const pc = new RTCPeerConnection({ iceServers: ice });

highlightNode(backendNodeId: number, frameId: string): void

Paints a debug overlay over the node identified by backendNodeId.

await browser.highlightNode(res.backendNodeId, res.frameId);

insertText(text: string): void

Pastes text at the current caret using IME-style input.

await browser.insertText("hello world");

inspectAtPosition(x: number, y: number): InspectResult

Hit-tests at the viewport-relative (x, y) and returns the topmost element under that point.

const r = await browser.inspectAtPosition(200, 300);
console.log(r.tagName, r.textContent);

listReactions(): ReactionInfo[]

Returns the still-pending reactions registered for the current page. Reactions that have already fired (one-shot) are not included.

const pending = await browser.listReactions();
for (const r of pending) console.log(r.reactionId, r.matchSelector);

loadHTML(url: string, html: string, opts: LoadHTMLOpts | undefined): void

Serves a synthetic response for the next navigation to url.

await browser.loadHTML("https://example.com", "<h1>hi</h1>");
await browser.navigate("https://example.com");

modifyRequest(urlPattern: string, opts: {
      body?: string;
      modifications?: HeaderModification[];
      timeoutMs?: number;
    } | undefined): InterceptedRequest | null

Waits for the next request whose URL matches urlPattern, applies the supplied header modifications (and optional body replacement), then forwards the modified request.

const req = await browser.modifyRequest("*\/api/me", {
modifications: [
  { action: "add", name: "X-Trace", value: "abc123" },
  { action: "remove", name: "Cookie" },
],
timeoutMs: 5000,
});
console.log("forwarded headers:", req?.headers);

moveTo(target: Locator): ElementResult

Moves the mouse cursor over the given target.

await browser.moveTo(css("nav .menu"));

navigate(url: string, opts: NavigateOpts | undefined): NavigateResult

Navigates the page to url.

await browser.navigate("https://example.com");

pressKey(key: string, opts: { code?: string; modifiers?: number; location?: number } | undefined): void

Fires a single key-down event.

// Ctrl+A
await browser.pressKey("a", { code: "KeyA", modifiers: 2 });
await browser.releaseKey("a", { code: "KeyA", modifiers: 2 });

readCanvas(target: Locator, opts: ReadCanvasOpts | undefined): ReadCanvasResult

Reads the pixels of a <canvas> element directly in the renderer, bypassing the origin-clean (tainted) security check and without executing any page JavaScript — so cross-origin/tainted canvases (common in captchas) read fine where a normal toDataURL / getImageData would throw a SecurityError.

const res = await browser.readCanvas(css("#game canvas"));
await fs.writeFile("canvas.png", Buffer.from(res.dataBase64, "base64"));

// Read the left half as JPEG at quality 80.
const res = await browser.readCanvas(css("canvas"), {
format: "jpeg", quality: 80, sw: 150, sh: 300,
});

releaseKey(key: string, opts: { code?: string; modifiers?: number; location?: number } | undefined): void

Fires a single key-up event.

await browser.pressKey("Shift", { code: "ShiftLeft", location: 1 });
await browser.releaseKey("Shift", { code: "ShiftLeft", location: 1 });

removeReaction(reactionId: string): boolean

Removes a pending reaction by id. Returns false if the reaction had already fired (one-shot) or was never registered.

const removed = await browser.removeReaction(id);

screenshot(opts: ScreenshotOpts | undefined): ScreenshotResult

Captures a single image of the page's current frame and returns it as base64-encoded image bytes.

const shot = await browser.screenshot({ format: "png" });
await fs.writeFile("page.png", Buffer.from(shot.dataBase64, "base64"));

scrollTo(target: Locator): ElementResult

Scrolls the given element into view.

await browser.scrollTo(css("#footer"));

selectByIndex(target: Locator, index: number, opts: SelectOpts | undefined): SelectOptionResult

Picks the <option> at the zero-based index inside the targeted <select> element.

await browser.selectByIndex(css("select#country"), 2);

// Pick the option silently, no input/change events.
await browser.selectByIndex(css("select#hidden"), 0, { fireEvents: false });

selectByText(target: Locator, text: string, opts: SelectOpts | undefined): SelectOptionResult

Picks the <option> whose visible (trimmed) text matches the given string exactly.

await browser.selectByText(css("select#country"), "Germany");

selectByValue(target: Locator, value: string, opts: SelectOpts | undefined): SelectOptionResult

Picks the <option> whose value attribute matches the given string exactly.

await browser.selectByValue(css("select#country"), "DE");

setAuthSession(session: AuthSession): void

Imports an auth session so the context comes up signed in (and syncing if syncConsent) with its DBSC sessions restored.

await browser.setAuthSession(saved);
await browser.navigate("https://mail.google.com");

setBlockList(patterns: string[]): void

Replaces the session's URL blocklist.

await browser.setBlockList([
"*.doubleclick.net/*",
"*googletagmanager.com*",
]);

setCookies(cookies: CookieParam[]): void

Writes the supplied cookies into the browser context.

await browser.setCookies([
{ name: "auth", value: "tok", domain: "example.com", path: "/" },
]);

setProxy(proxyHost: string, proxyPort: number, proxyUsername: string, proxyPassword: string): void

Changes the runtime proxy for this session.

await browser.setProxy("proxy.example.com", 8080, "user", "pass");

setStaticPaths(blobName: string, patterns: string[]): void

Configures the session to serve cached static responses for requests matching the given patterns from blobName.

await browser.setStaticPaths("snap-2026-05", ["*.example.com/*"]);

setStorage(storage: StorageOriginEntry[]): void

Writes localStorage entries into the browser context, grouped by origin.

await browser.setStorage([
{
  origin: "https://example.com",
  items: [
    { key: "token", value: "abc123" },
    { key: "theme", value: "dark" },
  ],
},
]);

solveCaptcha(opts: { timeoutMs?: number; retryAmount?: number } | undefined): string

Detects and solves the first supported bot-challenge it finds anywhere on the page.

await browser.solveCaptcha({ retryAmount: 2 });

startStream(offerSdp: string): string

Answers your WebRTC SDP offer and starts streaming the page as a video track, returning the SDP answer to set as your peer's remote description. The browser is the answerer; you are the offerer (see getStreamConfig for the credentials to build the offer).

const answer = await browser.startStream(offer.sdp);
await pc.setRemoteDescription({ type: "answer", sdp: answer });

stopStream(): void

Tears down the live video stream for the session's page. Safe to call even if no stream is running.

await browser.stopStream();

type(text: string, opts: { clearFirst?: boolean } | undefined): void

Types text into the currently focused element as a per-key stream of real keyboard events (keyDown/char/keyUp with the context's QWERTZ/QWERTY layout and human cadence) — unlike insertText, a single IME-style commit with no key events.

// OTP field that auto-advances across boxes.
await browser.click(css("input.otp-0"));
await browser.type("123456");

wait(condition: Locator, opts: WaitOpts | undefined): WaitResult

Blocks until the given locator matches.

await browser.wait(css(".success"));

waitAny(conditions: Locator[], opts: WaitOpts | undefined): WaitResult

Blocks until any of the supplied locators matches.

const r = await browser.waitAny(
[css(".success"), js("window.__ready === true")],
{ timeoutMs: 5000 },
);
console.log("matched index:", r.index);

waitForAnyRequest(patterns: RequestPattern[], opts: { timeoutMs?: number } | undefined): { index: number; request: InterceptedRequest | null }

Blocks until the next request whose URL matches one of the supplied patterns is observed.

const { index, request } = await browser.waitForAnyRequest(
[{ url: "*\/api/login" }],
{ timeoutMs: 5000 },
);
console.log(index, request?.method, request?.url);

waitForAnyResponse(patterns: RequestPattern[], opts: { timeoutMs?: number } | undefined): { index: number; response: InterceptedResponse | null }

Blocks until the next response whose URL matches one of the supplied patterns is observed.

const { index, response } = await browser.waitForAnyResponse(
[{ url: "*\/api/login" }],
{ timeoutMs: 5000 },
);
console.log(index, response?.statusCode);

inAllFrames(): Locator

Scopes this Locator to every frame.

await browser.wait(css("button.consent").inAllFrames());

inFrame(frameId: string): Locator

Scopes this Locator to a specific frameId.

const pages = await browser.getPages();
const iframeId = pages[0].frameTree.children[0].frameId;
await browser.click(css("button").inFrame(iframeId));

steady(ms: number): Locator

Requires the element to keep a stable position and size for at least ms milliseconds before the wait matches.

await browser.wait(css(".banner").steady(0));

visible(v: boolean): Locator

Enforces or disables the visibility check for this Locator's wait condition.

await browser.wait(css("#hidden").visible(false));

withCountryCode(countryCode: string): BrowserConfig

Sets the geo-IP country code for the rented session.

new BrowserConfig(apiKey, 600, "", 0, "", "").withCountryCode("DE");

withFingerprint(fingerprint: string): BrowserConfig

Pins a specific browser fingerprint id for the session.

new BrowserConfig(apiKey, 600, "", 0, "", "").withFingerprint("fp_abc123");

withTimezone(timezone: string): BrowserConfig

Sets the IANA timezone for the rented session.

new BrowserConfig(apiKey, 600, "", 0, "", "").withTimezone("Europe/Berlin");

at(x: number, y: number): Locator

at targets viewport coordinates instead of an element.

// Click at canvas-relative coordinates.
await browser.click(at(120, 240));

connectSession(grpcUrl: string, apiKey: string, sessionId: string): CloudBrowser

Attaches to an already-rented session over a fresh gRPC connection.

const browser = connectSession(grpcUrl, apiKey, sessionId);
try {
await browser.navigate("https://example.com");
} finally {
await browser.stopBrowser();
}

createWebSocketBrowser(wsUrl: string, sessionId: string, apiKey: string, fingerprint: string): CloudBrowser

Attaches a CloudBrowser to an existing session over a raw WebSocket transport.

const browser = createWebSocketBrowser(
"wss://session-abc.browserscale.example.com/ws",
sessionId,
apiKey,
);
await browser.navigate("https://example.com");

css(selector: string): Locator

css waits for / targets an element matching the given CSS selector.

// As a wait condition.
await browser.wait(css("button.submit"));
// As an action target.
await browser.click(css("button.submit"));

js(expression: string): Locator

js waits for / targets the result of a JavaScript expression.

await browser.wait(js("window.__ready === true"));

node(backendNodeId: number): Locator

node targets an element by its DevTools backendNodeId.

const r = await browser.click(css("button.open"));
await browser.click(node(r.backendNodeId));

rentBrowser(config: BrowserConfig): CloudBrowser

Rents a new browser session and returns a connected handle.

const cfg = new BrowserConfig("sk_…", 600, "", 0, "", "");
const browser = await rentBrowser(cfg);
try {
await browser.navigate("https://example.com");
} finally {
await browser.stopBrowser();
}

setApiEndpoint(endpoint: string): void

Overrides the HTTP rent/stop endpoint.

setApiEndpoint("https://browserscale.internal.example.com");

stopBrowser(apiKey: string, sessionId: string): void

Releases a session without needing a CloudBrowser handle.

await stopBrowser(apiKey, sessionId);

AuthSession is a portable snapshot of a context's signed-in Google account and/or DBSC sessions. Every field is optional, so a context that only has DBSC sessions (no primary account) or only a sign-in (no DBSC) round-trips.

BrowserScaleError is the base class for every error thrown by the SDK. It wraps either: - a client-side validation failure (bad locator, missing patterns, …) - a server-side gRPC error (Connect's ConnectError, available as cause)

type Button = "left" | "right" | "middle"

Mouse button used by CloudBrowser.click.

type ClickAction = "click" | "press" | "release"

Mouse phase performed by CloudBrowser.click.

ClickError is thrown by CloudBrowser.click when the click did not land — the target was found but another element covered the intended point. occluder describes the blocker; result carries the resolved element and coordinates (success is false).

Optional customization for CloudBrowser.click. All fields are optional; missing or zero values mean "use the server default".

CookieParam is one entry returned by getCookies() or passed to setCookies().

Partition metadata for partitioned cookies (CHIPS).

DbscSession is one Device Bound Session Credentials entry.

DOMResult is the full-tree DOM snapshot returned by CloudBrowser.getDOM, plus its sha256:8 hash for cheap change detection.

DragError is thrown by CloudBrowser.dragBy / CloudBrowser.dragTo when the source element could not be acquired/pressed. Drag picks up the source with the same smart click as CloudBrowser.click, so a pre-drag failure is a click failure: code mirrors it and the full click diagnostics live under clickError.

DragResult is the outcome of a CloudBrowser.drag gesture: the resolved source element and the start/end coordinates of the performed drag.

ElementRef is a lightweight descriptor of an element — enough to identify it (and decide what to do) without another DOM round-trip. It names the element that stole focus in a FillError focus-loss failure.

ElementResult is the outcome of an element interaction such as CloudBrowser.click, CloudBrowser.fill or CloudBrowser.scrollTo: the resolved element plus the root-relative coordinates the action was performed at.

EvaluateResult carries the outcome of a JS evaluate call.

FillError is thrown by CloudBrowser.fill when the field could not be focused/typed. The click-phase codes ("not_found", "occluded_no_reachable_point", "occluded_after_evade") mirror the underlying focus click, with diagnostics under clickError. The focus codes are "focus_stolen" (another element took focus — focusedElement names it; fill is strictly target-bound and will not type into the thief) and "focus_lost" (focus left the target and nothing is focused). For untargeted stream typing that lets focus move (e.g. OTP), use CloudBrowser.type.

Optional customization for CloudBrowser.fill. All fields are optional; missing values mean "use the server default".

FrameInfo describes a single frame within a page's frame tree.

Depth used by getDOM(). 0 = whole tree (default), >0 = limited depth.

Optional customization for CloudBrowser.getObservation.

Header is a single HTTP header (name/value pair) on an intercepted request or response.

HeaderModification is one entry passed to CloudBrowser.modifyRequest. Write it as a plain object literal.

type HeaderModificationAction = "add" | "edit" | "remove"

Action verb for a HeaderModification.

IceServer is one entry for a WebRTC RTCPeerConnection's iceServers config: a TURN (or STUN) URL plus the short-lived credentials to authenticate with it. Pass these to your peer before creating the offer.

InspectResult describes the topmost element hit at viewport-relative (x, y). backendNodeId === 0 means nothing was found at that position.

InterceptedRequest describes an outgoing request captured by CloudBrowser.waitForAnyRequest.

InterceptedResponse describes a network response captured by CloudBrowser.waitForAnyResponse.

Optional customization for CloudBrowser.loadHTML.

MoveError is thrown by CloudBrowser.moveTo when the target could not be located. A move has no occlusion notion, so this is the only semantic failure.

Optional customization for CloudBrowser.navigate.

NavigateResult reports where a CloudBrowser.navigate call ended up after redirects.

OccluderInfo describes the element that intercepted a click — the element sitting on top of the target at the intended click point. Coordinates are in root-viewport CSS pixels. Populated on ClickError for occlusion failures so the caller can locate and clear the blocker (e.g. find its close button).

PageInfo describes an open page (tab or popup) inside a browser context.

ReactionInfo describes a still-pending reaction, as returned by CloudBrowser.listReactions. One-shot reactions that have already fired are gone and never appear here.

Optional customization for CloudBrowser.addReaction. All fields are optional; missing or zero values mean "use the server default".

Optional customization for CloudBrowser.readCanvas.

ReadCanvasResult is the pixel readback of a <canvas>, returned by CloudBrowser.readCanvas. dataBase64 holds the encoded image bytes (PNG by default) or the raw RGBA buffer when format is "rgba". originClean reports whether the canvas was untainted (informational — the read succeeds either way).

Rect describes a position and size in CSS pixels.

RentResponse is the result of renting a browser via the REST API.

RequestPattern matches a URL pattern in waitForAnyRequest/Response. Set abort to true to drop the request with an empty 200 response instead of letting it through to the network.

Optional customization for CloudBrowser.screenshot.

ScreenshotResult is a single captured image of the page, returned by CloudBrowser.screenshot. dataBase64 holds the encoded image bytes (PNG by default); width and height are in physical pixels.

ScrollError is thrown by CloudBrowser.scrollTo when the target could not be located/scrolled.

SelectOptionError is thrown by the CloudBrowser.selectByIndex / selectByValue / selectByText calls when the option could not be selected. selectOption is programmatic (no pointer gate), so it only reports semantic failures.

SelectOptionResult reports which option a selectByXxx call ended up selecting.

Optional customization for CloudBrowser.selectByIndex, CloudBrowser.selectByValue and CloudBrowser.selectByText.

StorageItem is a single localStorage key/value pair.

StorageOriginEntry groups the localStorage entries of one origin (e.g. "https://example.com"). getStorage() returns these and setStorage() accepts the same shape, so a dump can be fed back verbatim.

WaitConditionStatus is the per-condition diagnostic carried by WaitError when a CloudBrowser.wait times out: one entry per condition (in the order they were passed) explaining why it never matched.

WaitError is thrown by CloudBrowser.wait / CloudBrowser.waitAny when no condition matched before the deadline. conditions holds the per-condition breakdown (same order/length as the conditions passed in) explaining why each one never matched.

Optional customization for CloudBrowser.wait / CloudBrowser.waitForAny.

WaitResult is the outcome of a CloudBrowser.wait / CloudBrowser.waitForAny call: which condition matched (index, in argument order) and where the matched element lives.

type WaitUntil = "load" | "domcontentloaded" | "networkidle"

Lifecycle event CloudBrowser.navigate waits for before returning.