API Reference

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

Core Types

CloudBrowser

The main client for interacting with cloud browsers.

type CloudBrowser struct

Header

HTTP header representation.

type Header struct 
    Name  string
    Value string
}

Cookie

Browser cookie representation.

type Cookie struct 
    Name   string
    Value  string
    Domain string
    Path   string
}

Request

Network request representation.

type Request struct 
    Method     string
    Url        string
    Headers    []*Header
    Body       string
    StatusCode int
}

Response

Network response representation.

type Response struct 
    Url        string
    Headers    []*Header
    Body       string
    StatusCode int
}

HeaderModification

Header modification for request interception.

type HeaderModification struct 
    Name   string
    Value  string
    Action HeaderModificationAction
    After  string
    Before string
}

HeaderModificationAction

Action type for header modifications.

type HeaderModificationAction int

const (
    HeaderModificationAdd HeaderModificationAction = iota
    HeaderModificationEdit
    HeaderModificationRemove
}

FrameTree

Frame tree structure for frame hierarchy.

type FrameTree struct 
    FrameId  string
    PosX     int32
    PosY     int32
    Children []*FrameTree
}

Session Management

RentBrowser

Create a new cloud browser session.

func RentBrowser(ctx context.Context, apiKey string, rentTime int, proxyHost string, proxyPort int, proxyUsername string, proxyPassword string, countryCode string, timezone string, blobName string) (*CloudBrowser, error)

Parameters:

ctx: Context for cancellation
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:

*CloudBrowser: A configured browser instance ready for automation
error: Any error that occurred during browser creation

StopBrowser

Terminate an active browser session.

func StopBrowser(ctx context.Context, apiKey string, sessionId string) error

Parameters:

ctx: Context for cancellation
apiKey: WebRobotCloud API key
sessionId: Session ID of the browser to stop

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

(*CloudBrowser) StopBrowser

Stop the current session and close the underlying gRPC connection.

func (c *CloudBrowser) StopBrowser(ctx context.Context) error

Parameters:

ctx: Context for cancellation

Session Info

Access session metadata returned by the rent response.

func (c *CloudBrowser) GetSessionId() string
func (c *CloudBrowser) GetApiKey() string
func (c *CloudBrowser) GetGrpcUrl() string
func (c *CloudBrowser) GetCountryCode() string
func (c *CloudBrowser) GetTimezone() string
func (c *CloudBrowser) GetAcceptLanguage() string

Close

Convenience method to stop the browser session using a background context.

func (c *CloudBrowser) Close() error

UploadStaticFiles

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

func UploadStaticFiles(ctx context.Context, apiKey string, blobName string, localPath string) error

Parameters:

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

Returns:

error: 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 fs.FS (including embed.FS) to the WebRobotCloud server.

func UploadStaticFilesFromFS(ctx context.Context, apiKey string, blobName string, filesystem fs.FS) error

Parameters:

ctx: Context for cancellation
apiKey: WebRobotCloud API key
blobName: Name of the blob to store the files under
filesystem: Filesystem containing files to upload (e.g., embed.FS)

Returns:

error: 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.

func (c *CloudBrowser) Navigate(ctx context.Context, url string, timeoutMs int32) error

Parameters:

ctx: Context for cancellation
url: URL to navigate to
timeoutMs: Timeout in milliseconds

LoadHTML

Load HTML content directly into the browser.

func (c *CloudBrowser) LoadHTML(ctx context.Context, url string, html string) error

Parameters:

ctx: Context for cancellation
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).

func (c *CloudBrowser) ClickSelector(ctx context.Context, selector string) error

Parameters:

ctx: Context for cancellation
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.

func (c *CloudBrowser) ClickSelectorInFrame(ctx context.Context, frameId string, selector string) error

Parameters:

ctx: Context for cancellation
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).

func (c *CloudBrowser) FillInput(ctx context.Context, selector string, value string) error

Parameters:

ctx: Context for cancellation
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.

func (c *CloudBrowser) FillInputInFrame(ctx context.Context, frameId string, selector string, value string) error

Parameters:

ctx: Context for cancellation
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).

func (c *CloudBrowser) SelectOption(ctx context.Context, selector string, option string) error

Parameters:

ctx: Context for cancellation
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.

func (c *CloudBrowser) SelectOptionInFrame(ctx context.Context, frameId string, selector string, option string) error

Parameters:

ctx: Context for cancellation
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.

func (c *CloudBrowser) Type(ctx context.Context, text string) error

Parameters:

ctx: Context for cancellation
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.

func (c *CloudBrowser) TypeInFrame(ctx context.Context, frameId string, text string) error

Parameters:

ctx: Context for cancellation
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.

func (c *CloudBrowser) MoveMouseToSelector(ctx context.Context, selector string) (int32, int32, error)

Parameters:

ctx: Context for cancellation
selector: CSS selector for the element

Returns:

int32: X coordinate
int32: Y coordinate
error: Any error that occurred

MoveMouseToSelectorInFrame

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

func (c *CloudBrowser) MoveMouseToSelectorInFrame(ctx context.Context, frameId string, selector string) (int32, int32, error)

Parameters:

ctx: Context for cancellation
frameId: Frame ID (or "ROOT_FRAME")
selector: CSS selector for the element

Returns:

int32: X coordinate
int32: Y coordinate
error: Any error that occurred

PressPosition

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

func (c *CloudBrowser) PressPosition(ctx context.Context, x int32, y int32) error

Parameters:

ctx: Context for cancellation
x: X coordinate to press
y: Y coordinate to press

ReleasePosition

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

func (c *CloudBrowser) ReleasePosition(ctx context.Context, x int32, y int32) error

Parameters:

ctx: Context for cancellation
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).

func (c *CloudBrowser) Evaluate(ctx context.Context, expression string) (interface, error)

Parameters:

ctx: Context for cancellation
expression: JavaScript expression to execute

Returns:

interface: Result of the JavaScript expression
error: Any error that occurred during execution

EvaluateInFrame

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

func (c *CloudBrowser) EvaluateInFrame(ctx context.Context, expression string, frameId string) (interface, error)

Parameters:

ctx: Context for cancellation
expression: JavaScript expression to execute
frameId: Frame ID to execute in

Returns:

interface: Result of the JavaScript expression
error: Any error that occurred during execution

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).

func (c *CloudBrowser) WaitForSelector(ctx context.Context, selector string, timeoutMs int32) error

Parameters:

ctx: Context for cancellation
selector: CSS selector to wait for
timeoutMs: Timeout in milliseconds

Returns:

error: Any error that occurred during the wait operation

WaitForSelectorGlobal

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

func (c *CloudBrowser) WaitForSelectorGlobal(ctx context.Context, selector string, timeoutMs int32) (string, error)

Parameters:

ctx: Context for cancellation
selector: CSS selector to wait for
timeoutMs: Timeout in milliseconds

Returns:

string: Frame ID where the selector was found
error: Any error that occurred during the wait operation

WaitForExpression

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

func (c *CloudBrowser) WaitForExpression(ctx context.Context, expression string, timeoutMs int32) error

Parameters:

ctx: Context for cancellation
expression: JavaScript expression to wait for
timeoutMs: Timeout in milliseconds

Returns:

error: Any error that occurred during the wait operation

WaitForExpressionGlobal

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

func (c *CloudBrowser) WaitForExpressionGlobal(ctx context.Context, expression string, timeoutMs int32) (string, error)

Parameters:

ctx: Context for cancellation
expression: JavaScript expression to wait for
timeoutMs: Timeout in milliseconds

Returns:

string: Frame ID where the expression returned true
error: Any error that occurred during the wait operation

WaitForAnySelector

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

func (c *CloudBrowser) WaitForAnySelector(ctx context.Context, selectors []string, timeoutMs int32) (int32, error)

Parameters:

ctx: Context for cancellation
selectors: Array of CSS selectors to wait for
timeoutMs: Timeout in milliseconds

Returns:

int32: Index of the first matching selector
error: Any error that occurred during the wait operation

WaitForAnySelectorGlobal

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

func (c *CloudBrowser) WaitForAnySelectorGlobal(ctx context.Context, selectors []string, timeoutMs int32) (int32, string, error)

Parameters:

ctx: Context for cancellation
selectors: Array of CSS selectors to wait for
timeoutMs: Timeout in milliseconds

Returns:

int32: Index of the first matching selector
string: Frame ID where the selector was found
error: Any error that occurred during the wait operation

WaitForAnyExpression

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

func (c *CloudBrowser) WaitForAnyExpression(ctx context.Context, expressions []string, timeoutMs int32) (int32, error)

Parameters:

ctx: Context for cancellation
expressions: Array of JavaScript expressions to wait for
timeoutMs: Timeout in milliseconds

Returns:

int32: Index of the first matching expression
error: Any error that occurred during the wait operation

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.

func (c *CloudBrowser) WaitForAnyExpressionGlobal(ctx context.Context, expressions []string, timeoutMs int32) (int32, string, error)

Parameters:

ctx: Context for cancellation
expressions: Array of JavaScript expressions to wait for
timeoutMs: Timeout in milliseconds

Returns:

int32: Index of the first matching expression
string: Frame ID where the expression returned true
error: Any error that occurred during the wait operation

WaitForSelectorInFrame

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

func (c *CloudBrowser) WaitForSelectorInFrame(ctx context.Context, frameId string, selector string, timeoutMs int32) (string, error)

Parameters:

ctx: Context for cancellation
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
error: Any error that occurred during the wait operation

WaitForExpressionInFrame

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

func (c *CloudBrowser) WaitForExpressionInFrame(ctx context.Context, frameId string, expression string, timeoutMs int32) (string, error)

Parameters:

ctx: Context for cancellation
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
error: Any error that occurred during the wait operation

WaitForAnySelectorInFrame

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

func (c *CloudBrowser) WaitForAnySelectorInFrame(ctx context.Context, frameId string, selectors []string, timeoutMs int32) (int32, string, error)

Parameters:

ctx: Context for cancellation
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:

int32: Index of the first matching selector
string: Frame ID where the selector was found
error: Any error that occurred during the wait operation

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.

func (c *CloudBrowser) WaitForAnyExpressionInFrame(ctx context.Context, frameId string, expressions []string, timeoutMs int32) (int32, string, error)

Parameters:

ctx: Context for cancellation
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:

int32: Index of the first matching expression
string: Frame ID where the expression returned true
error: Any error that occurred during the wait operation

Frame Management

GetFrames

Get all available frame IDs.

func (c *CloudBrowser) GetFrames(ctx context.Context) ([]string, error)

Parameters:

ctx: Context for cancellation

Returns:

[]string: Array of frame IDs
error: Any error that occurred during the operation

GetFrameTree

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

func (c *CloudBrowser) GetFrameTree(ctx context.Context) (*FrameTree, error)

Parameters:

ctx: Context for cancellation

Returns:

*FrameTree: Frame tree structure
error: Any error that occurred during the operation

Network Operations

WaitForRequest

Wait for a specific network request.

func (c *CloudBrowser) WaitForRequest(ctx context.Context, url string, abort bool, timeoutMs int32) (*Request, error)

Parameters:

ctx: Context for cancellation
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
error: Any error that occurred during the wait operation

WaitForResponse

Wait for a specific network response.

func (c *CloudBrowser) WaitForResponse(ctx context.Context, url string, timeoutMs int32) (*Response, error)

Parameters:

ctx: Context for cancellation
url: URL pattern to wait for
timeoutMs: Timeout in milliseconds

Returns:

*Response: Response object with URL, headers, body, and status code
error: Any error that occurred during the wait operation

WaitForAnyRequest

Wait for any of multiple network requests.

func (c *CloudBrowser) WaitForAnyRequest(ctx context.Context, urlPatterns []string, abortFlags []bool, timeoutMs int32) (int32, *Request, error)

Parameters:

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

Returns:

int32: Index of the matching request
*Request: Request object with method, URL, headers, body, and status code
error: Any error that occurred during the wait operation

WaitForAnyResponse

Wait for any of multiple network responses.

func (c *CloudBrowser) WaitForAnyResponse(ctx context.Context, urlPatterns []string, timeoutMs int32) (int32, *Response, error)

Parameters:

ctx: Context for cancellation
urlPatterns: Array of URL patterns to wait for
timeoutMs: Timeout in milliseconds

Returns:

int32: Index of the matching response
*Response: Response object with URL, headers, body, and status code
error: Any error that occurred during the wait operation

ModifyRequest

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

func (c *CloudBrowser) ModifyRequest(ctx context.Context, urlPattern string, timeoutMs int32, modifications []*HeaderModification, body string) (*Request, error)

Parameters:

ctx: Context for cancellation
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
error: Any error that occurred during the modification operation

SetBlockList

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

func (c *CloudBrowser) SetBlockList(ctx context.Context, patterns []string) error

Parameters:

ctx: Context for cancellation
patterns: Array of URL patterns to block (supports wildcard *)

Returns:

error: Any error that occurred during the operation

Cookie Management

GetCookies

Get all browser cookies.

func (c *CloudBrowser) GetCookies(ctx context.Context) ([]*Cookie, error)

Parameters:

ctx: Context for cancellation

Returns:

[]*Cookie: Array of cookie objects
error: Any error that occurred during the operation

SetCookies

Set cookies for the current browser session.

func (c *CloudBrowser) SetCookies(ctx context.Context, cookies []*Cookie) error

Parameters:

ctx: Context for cancellation
cookies: Cookies to set (name, value, domain, path)

Returns:

error: Any error that occurred during the operation

ClearCookies

Clear all cookies for the current browser session.

func (c *CloudBrowser) ClearCookies(ctx context.Context) error

Parameters:

ctx: Context for cancellation

Returns:

error: Any error that occurred during the operation

Captcha Solving

SolveCaptcha

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

func (c *CloudBrowser) SolveCaptcha(ctx context.Context, timeoutMs int32, retryAmount ...int32) (string, error)

Parameters:

ctx: Context for cancellation
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
error: Transport/handling error (if any)

Documentation

API Reference

Core Types

CloudBrowser

Header

Cookie

Request

Response

HeaderModification

HeaderModificationAction

FrameTree

Session Management

RentBrowser

StopBrowser

(*CloudBrowser) StopBrowser

Session Info

Close

UploadStaticFiles

UploadStaticFilesFromFS

Browser Operations

Navigate

LoadHTML

ClickSelector

ClickSelectorInFrame

FillInput

FillInputInFrame

SelectOption

SelectOptionInFrame

Type

TypeInFrame

MoveMouseToSelector

MoveMouseToSelectorInFrame

PressPosition

ReleasePosition

JavaScript Execution

Evaluate

EvaluateInFrame

Waiting Operations

Frame Targeting Modes

WaitForSelector

WaitForSelectorGlobal

WaitForExpression

WaitForExpressionGlobal

WaitForAnySelector

WaitForAnySelectorGlobal

WaitForAnyExpression

WaitForAnyExpressionGlobal

WaitForSelectorInFrame

WaitForExpressionInFrame

WaitForAnySelectorInFrame

WaitForAnyExpressionInFrame

Frame Management

GetFrames

GetFrameTree

Network Operations

WaitForRequest

WaitForResponse

WaitForAnyRequest

WaitForAnyResponse

ModifyRequest

SetBlockList

Cookie Management

GetCookies

SetCookies

ClearCookies

Captcha Solving

SolveCaptcha