WebRobotCloud logo
WebRobotCloudCloud Browser Automation
Client Panel

Documentation

API Reference

Complete API reference for the TypeScript SDK. All types, functions, parameters, and return values.

Core Types

CloudBrowser

The main client for interacting with cloud browsers.

export class CloudBrowser

Header

HTTP header representation.

export interface Header name: string; value: string; }

Cookie

Browser cookie representation.

export interface Cookie name: string; value: string; domain: string; path: string; }

Request

Network request representation.

export interface Request method: string; url: string; headers: Header[]; body: string; statusCode: number; }

Response

Network response representation.

export interface Response url: string; headers: Header[]; body: string; statusCode: number; }

HeaderModification

Header modification for request interception.

export interface HeaderModification name: string; value: string; action: HeaderModificationAction; after?: string; before?: string; }

HeaderModificationAction

Action type for header modifications.

export enum HeaderModificationAction Add = "HEADER_MODIFICATION_ADD", Edit = "HEADER_MODIFICATION_EDIT", Remove = "HEADER_MODIFICATION_REMOVE" }

FrameTree

Frame tree structure for frame hierarchy.

export interface FrameTree frameId: string; posX: number; posY: number; children: FrameTree[]; }

FileEntry

Static file entry used for in-memory uploads.

export interface FileEntry path: string; data: Buffer | Uint8Array | string; }

EvaluateResult

JSON-friendly result returned by evaluate methods.

export type EvaluateResult = string | number | boolean | null | EvaluateResult[] | { [key: string]: EvaluateResult }

Session Management

rentBrowser

Create a new cloud browser session.

rentBrowser(apiKey, rentTime, proxyHost, proxyPort, proxyUsername, proxyPassword, countryCode, timezone, blobName): Promise<CloudBrowser>

Parameters:

  • apiKey: WebRobotCloud API key
  • rentTime: Duration in seconds to rent the browser
  • proxyHost: Proxy server hostname
  • proxyPort: Proxy server port
  • proxyUsername: Proxy authentication username
  • proxyPassword: Proxy authentication password
  • countryCode: Two-letter country code for proxy location (optional, "" for auto)
  • timezone: Timezone string (optional, "" for auto)
  • blobName: Name of the static file blob to use (optional, "" for no static files)

Returns:

  • Promise<CloudBrowser>: A configured browser instance ready for automation

stopBrowser

Terminate an active browser session.

stopBrowser(apiKey, sessionId): Promise<void>

Parameters:

  • apiKey: WebRobotCloud API key
  • sessionId: Session ID of the browser to stop

Note: You can also call browser.stopBrowser() on a CloudBrowser instance to stop the current session.

CloudBrowser.stopBrowser

Stop the current session and close the underlying gRPC connection.

browser.stopBrowser(): Promise<void>

Session Info

Access session metadata returned by the rent response.

browser.getSessionId() browser.getApiKey() browser.getGrpcUrl() browser.getCountryCode() browser.getTimezone() browser.getAcceptLanguage()

Close

Convenience method to stop the browser session.

browser.close(): Promise<void>

uploadStaticFiles

Upload static files from a local directory to the WebRobotCloud server.

uploadStaticFiles(apiKey, blobName, localPath): Promise<void>

Parameters:

  • apiKey: WebRobotCloud API key
  • blobName: Name of the blob to store the files under
  • localPath: Local directory path containing files to upload

Returns:

  • Promise<void>: Any error that occurred during the upload operation

Note: Each upload completely overwrites any previously uploaded static files for the given blob name. The newest upload replaces all previous files.

uploadStaticFilesFromFS

Upload static files from an in-memory file list to the WebRobotCloud server.

uploadStaticFilesFromFS(apiKey, blobName, files): Promise<void>

Parameters:

  • apiKey: WebRobotCloud API key
  • blobName: Name of the blob to store the files under
  • files: Files to upload (path + data)

Returns:

  • Promise<void>: Any error that occurred during the upload operation

Note: Each upload completely overwrites any previously uploaded static files for the given blob name. The newest upload replaces all previous files.

Browser Operations

navigate

Navigate to a URL with optional timeout.

browser.navigate(url, timeoutMs): Promise<void>

Parameters:

  • url: URL to navigate to
  • timeoutMs: Timeout in milliseconds

loadHTML

Load HTML content directly into the browser.

browser.loadHTML(url, html): Promise<void>

Parameters:

  • url: URL to load the HTML content at (emulated)
  • html: HTML content to load

clickSelector

Click an element using CSS selector in the page's top frame (ROOT_FRAME).

browser.clickSelector(selector): Promise<void>

Parameters:

  • selector: CSS selector for the element

Note: If the element is inside an iframe, first find the frame (e.g. waitForSelectorGlobal) and then use clickSelectorInFrame.

clickSelectorInFrame

Click an element using CSS selector inside a specific frame.

browser.clickSelectorInFrame(frameId, selector): Promise<void>

Parameters:

  • frameId: Frame ID (or "ROOT_FRAME")
  • selector: CSS selector for the element

fillInput

Fill an input field with a value in the page's top frame (ROOT_FRAME).

browser.fillInput(selector, value): Promise<void>

Parameters:

  • selector: CSS selector for the input element
  • value: Value to fill into the input field

fillInputInFrame

Fill an input field with a value inside a specific frame.

browser.fillInputInFrame(frameId, selector, value): Promise<void>

Parameters:

  • frameId: Frame ID (or "ROOT_FRAME")
  • selector: CSS selector for the input element
  • value: Value to fill into the input field

selectOption

Select an option from a select element in the page's top frame (ROOT_FRAME).

browser.selectOption(selector, option): Promise<void>

Parameters:

  • selector: CSS selector for the select element
  • option: Option value or text to select

selectOptionInFrame

Select an option from a select element inside a specific frame.

browser.selectOptionInFrame(frameId, selector, option): Promise<void>

Parameters:

  • frameId: Frame ID (or "ROOT_FRAME")
  • selector: CSS selector for the select element
  • option: Option value or text to select

type

Type text into the currently focused element.

browser.type(text): Promise<void>

Parameters:

  • text: Text to type into the focused element

Note: This method types into whatever element currently has focus. Use clickSelector or fillInput first to focus an element if needed.

typeInFrame

Type text into the currently focused element inside a specific frame.

browser.typeInFrame(frameId, text): Promise<void>

Parameters:

  • frameId: Frame ID (or "ROOT_FRAME")
  • text: Text to type into the focused element

Note: This method types into whatever element currently has focus in that frame. Focus an element first if needed.

moveMouseToSelector

Move mouse to an element using CSS selector in the page's top frame (ROOT_FRAME). Returns the coordinates where the mouse was moved.

browser.moveMouseToSelector(selector): Promise<{ x: number; y: number }>

Parameters:

  • selector: CSS selector for the element

Returns:

  • x: X coordinate
  • y: Y coordinate

moveMouseToSelectorInFrame

Move mouse to an element using CSS selector inside a specific frame.

browser.moveMouseToSelectorInFrame(frameId, selector): Promise<{ x: number; y: number }>

Parameters:

  • frameId: Frame ID (or "ROOT_FRAME")
  • selector: CSS selector for the element

Returns:

  • x: X coordinate
  • y: Y coordinate

pressPosition

Press mouse button at a specific position (x, y coordinates).

browser.pressPosition(x, y): Promise<void>

Parameters:

  • x: X coordinate to press
  • y: Y coordinate to press

releasePosition

Release mouse button at a specific position (x, y coordinates).

browser.releasePosition(x, y): Promise<void>

Parameters:

  • x: X coordinate to release
  • y: Y coordinate to release

JavaScript Execution

evaluate

Execute JavaScript expression and return the result in the page's top frame (ROOT_FRAME).

browser.evaluate(expression): Promise<EvaluateResult>

Parameters:

  • expression: JavaScript expression to execute

Returns:

  • EvaluateResult: Result of the JavaScript expression

evaluateInFrame

Execute JavaScript expression and return the result in a specific frame.

browser.evaluateInFrame(expression, frameId): Promise<EvaluateResult>

Parameters:

  • expression: JavaScript expression to execute
  • frameId: Frame ID to execute in

Returns:

  • EvaluateResult: Result of the JavaScript expression

Waiting Operations

Frame Targeting Modes

The waiting operations support three frame targeting modes:

  • Default methods (waitFor...): Search only in the page's top frame (ROOT_FRAME)
  • Global methods (waitFor...Global): Search across all frames globally
  • Frame-specific methods (waitFor...InFrame): Search only in a specific frame

waitForSelector

Wait for an element to appear in the page's top frame (ROOT_FRAME).

browser.waitForSelector(selector, timeoutMs): Promise<void>

Parameters:

  • selector: CSS selector to wait for
  • timeoutMs: Timeout in milliseconds

waitForSelectorGlobal

Wait for an element to appear and return the frame ID where it was found. Searches across all frames globally.

browser.waitForSelectorGlobal(selector, timeoutMs): Promise<string>

Parameters:

  • selector: CSS selector to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • string: Frame ID where the selector was found

waitForExpression

Wait for a JavaScript expression to return true in the page's top frame (ROOT_FRAME).

browser.waitForExpression(expression, timeoutMs): Promise<void>

Parameters:

  • expression: JavaScript expression to wait for
  • timeoutMs: Timeout in milliseconds

waitForExpressionGlobal

Wait for a JavaScript expression to return true and return the frame ID where it was found. Searches across all frames globally.

browser.waitForExpressionGlobal(expression, timeoutMs): Promise<string>

Parameters:

  • expression: JavaScript expression to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • string: Frame ID where the expression returned true

waitForAnySelector

Wait for any of multiple selectors to appear in the page's top frame (ROOT_FRAME).

browser.waitForAnySelector(selectors, timeoutMs): Promise<number>

Parameters:

  • selectors: Array of CSS selectors to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • number: Index of the first matching selector

waitForAnySelectorGlobal

Wait for any of multiple selectors to appear and return the frame ID where it was found. Searches across all frames globally.

browser.waitForAnySelectorGlobal(selectors, timeoutMs): Promise<{ index: number; frameId: string }>

Parameters:

  • selectors: Array of CSS selectors to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • index: Index of the first matching selector
  • frameId: Frame ID where the selector was found

waitForAnyExpression

Wait for any of multiple JavaScript expressions to return true in the page's top frame (ROOT_FRAME).

browser.waitForAnyExpression(expressions, timeoutMs): Promise<number>

Parameters:

  • expressions: Array of JavaScript expressions to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • number: Index of the first matching expression

waitForAnyExpressionGlobal

Wait for any of multiple JavaScript expressions to return true and return the frame ID where it was found. Searches across all frames globally.

browser.waitForAnyExpressionGlobal(expressions, timeoutMs): Promise<{ index: number; frameId: string }>

Parameters:

  • expressions: Array of JavaScript expressions to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • index: Index of the first matching expression
  • frameId: Frame ID where the expression returned true

waitForSelectorInFrame

Wait for an element to appear in a specific frame (not children). Use this when you know the exact frame ID.

browser.waitForSelectorInFrame(frameId, selector, timeoutMs): Promise<string>

Parameters:

  • frameId: Frame ID to search in (can be a specific frame ID or "ROOT_FRAME" for the page's top frame)
  • selector: CSS selector to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • string: Frame ID where the selector was found

waitForExpressionInFrame

Wait for a JavaScript expression to return true in a specific frame (not children). Use this when you know the exact frame ID.

browser.waitForExpressionInFrame(frameId, expression, timeoutMs): Promise<string>

Parameters:

  • frameId: Frame ID to search in (can be a specific frame ID or "ROOT_FRAME" for the page's top frame)
  • expression: JavaScript expression to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • string: Frame ID where the expression returned true

waitForAnySelectorInFrame

Wait for any of multiple selectors to appear in a specific frame (not children). Use this when you know the exact frame ID.

browser.waitForAnySelectorInFrame(frameId, selectors, timeoutMs): Promise<{ index: number; frameId: string }>

Parameters:

  • frameId: Frame ID to search in (can be a specific frame ID or "ROOT_FRAME" for the page's top frame)
  • selectors: Array of CSS selectors to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • index: Index of the first matching selector
  • frameId: Frame ID where the selector was found

waitForAnyExpressionInFrame

Wait for any of multiple JavaScript expressions to return true in a specific frame (not children). Use this when you know the exact frame ID.

browser.waitForAnyExpressionInFrame(frameId, expressions, timeoutMs): Promise<{ index: number; frameId: string }>

Parameters:

  • frameId: Frame ID to search in (can be a specific frame ID or "ROOT_FRAME" for the page's top frame)
  • expressions: Array of JavaScript expressions to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • index: Index of the first matching expression
  • frameId: Frame ID where the expression returned true

Frame Management

getFrames

Get all available frame IDs.

browser.getFrames(): Promise<string[]>

Returns:

  • string[]: Array of frame IDs

getFrameTree

Get the frame tree structure showing the hierarchy of all frames.

browser.getFrameTree(): Promise<FrameTree | null>

Returns:

  • FrameTree | null: Frame tree structure

Network Operations

waitForRequest

Wait for a specific network request.

browser.waitForRequest(url, abort, timeoutMs): Promise<Request>

Parameters:

  • url: URL pattern to wait for
  • abort: Whether to abort the request
  • timeoutMs: Timeout in milliseconds

Returns:

  • Request: Request object with method, URL, headers, body, and status code

waitForResponse

Wait for a specific network response.

browser.waitForResponse(url, timeoutMs): Promise<Response>

Parameters:

  • url: URL pattern to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • Response: Response object with URL, headers, body, and status code

waitForAnyRequest

Wait for any of multiple network requests.

browser.waitForAnyRequest(urlPatterns, abortFlags, timeoutMs): Promise<{ index: number; request: Request }>

Parameters:

  • urlPatterns: Array of URL patterns to wait for
  • abortFlags: Array of abort flags corresponding to each URL pattern
  • timeoutMs: Timeout in milliseconds

Returns:

  • index: Index of the matching request
  • request: Request object with method, URL, headers, body, and status code

waitForAnyResponse

Wait for any of multiple network responses.

browser.waitForAnyResponse(urlPatterns, timeoutMs): Promise<{ index: number; response: Response }>

Parameters:

  • urlPatterns: Array of URL patterns to wait for
  • timeoutMs: Timeout in milliseconds

Returns:

  • index: Index of the matching response
  • response: Response object with URL, headers, body, and status code

modifyRequest

Modify network requests by adding, editing, or removing headers and optionally changing the request body.

browser.modifyRequest(urlPattern, timeoutMs, modifications, body): Promise<Request>

Parameters:

  • urlPattern: URL pattern to match requests for modification
  • timeoutMs: Timeout in milliseconds
  • modifications: Array of header modifications to apply
  • body: Optional new request body (only applies to POST requests)

Returns:

  • Request: Modified request object

setBlockList

Set URL patterns to block. Requests matching these patterns will be blocked.

browser.setBlockList(patterns): Promise<void>

Parameters:

  • patterns: Array of URL patterns to block (supports wildcard *)

Cookie Management

getCookies

Get all browser cookies.

browser.getCookies(): Promise<Cookie[]>

Returns:

  • Cookie[]: Array of cookie objects

setCookies

Set cookies for the current browser session.

browser.setCookies(cookies): Promise<void>

Parameters:

  • cookies: Cookies to set (name, value, domain, path)

clearCookies

Clear all cookies for the current browser session.

browser.clearCookies(): Promise<void>

Captcha Solving

solveCaptcha

Attempt to auto-detect and solve a supported captcha on the current page (PerimeterX, Cloudflare Turnstile, DataDome).

browser.solveCaptcha(timeoutMs, retryAmount?): Promise<string>

Parameters:

  • timeoutMs: Overall timeout in milliseconds (0 uses default)
  • retryAmount: Optional retry budget (primarily for Px). If omitted, SDK uses a default.

Returns:

  • string: Empty string on success; error-like string on failure