WebRobotCloud logo
WebRobotCloudCloud Browser Automation
Client Panel

Documentation

API Reference

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

Core Types

CloudBrowser

The main client for interacting with cloud browsers.

class CloudBrowser

Header

HTTP header representation.

@dataclass class Header: name: str value: str

Cookie

Browser cookie representation.

@dataclass class Cookie: name: str value: str domain: str path: str

Request

Network request representation.

@dataclass class Request: method: str url: str headers: List[Header] body: str status_code: int

Response

Network response representation.

@dataclass class Response: url: str headers: List[Header] body: str status_code: int

HeaderModification

Header modification for request interception.

@dataclass class HeaderModification: name: str value: str action: HeaderModificationAction after: str = "" before: str = ""

HeaderModificationAction

Action type for header modifications.

class HeaderModificationAction(Enum): ADD = "HEADER_MODIFICATION_ADD" EDIT = "HEADER_MODIFICATION_EDIT" REMOVE = "HEADER_MODIFICATION_REMOVE"

FrameTree

Frame tree structure for frame hierarchy.

@dataclass class FrameTree: frame_id: str pos_x: int pos_y: int children: List[FrameTree]

FileEntry

Static file entry used for in-memory uploads.

@dataclass class FileEntry: path: str data: bytes | bytearray | str

EvaluateResult

JSON-friendly result returned by evaluate methods.

EvaluateResult = str | int | float | bool | None | List[EvaluateResult] | Dict[str, EvaluateResult]

Session Management

rent_browser

Create a new cloud browser session.

rent_browser(api_key, rent_time, proxy_host, proxy_port, proxy_username, proxy_password, country_code="", timezone="", blob_name="") -> CloudBrowser

Parameters:

  • api_key: WebRobotCloud API key
  • rent_time: Duration in seconds to rent the browser
  • proxy_host: Proxy server hostname
  • proxy_port: Proxy server port
  • proxy_username: Proxy authentication username
  • proxy_password: Proxy authentication password
  • country_code: Two-letter country code for proxy location (optional, "" for auto)
  • timezone: Timezone string (optional, "" for auto)
  • blob_name: Name of the static file blob to use (optional, "" for no static files)

Returns:

  • CloudBrowser: A configured browser instance ready for automation

stop_browser

Terminate an active browser session.

stop_browser(api_key, session_id) -> None

Parameters:

  • api_key: WebRobotCloud API key
  • session_id: Session ID of the browser to stop

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

CloudBrowser.stop_browser

Stop the current session and close the underlying gRPC connection.

browser.stop_browser() -> None

set_api_endpoint

Override the API endpoint used for rent/stop/static uploads.

set_api_endpoint(endpoint) -> None

Parameters:

  • endpoint: Base URL for the Browser Cloud API

upload_static_files

Upload static files from a local directory.

upload_static_files(api_key, blob_name, local_path) -> None

Parameters:

  • api_key: WebRobotCloud API key
  • blob_name: Name of the blob to store the files under
  • local_path: Local directory path containing files

Returns:

  • None: 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.

upload_static_files_from_files

Upload static files from an in-memory list of file entries.

upload_static_files_from_files(api_key, blob_name, files) -> None

Parameters:

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

Returns:

  • None: 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.

upload_static_files_from_fs

Alias for upload_static_files_from_files.

upload_static_files_from_fs(api_key, blob_name, files) -> None

Session Info

Access session metadata returned by the rent response.

browser.get_session_id() browser.get_api_key() browser.get_grpc_url() browser.get_country_code() browser.get_timezone() browser.get_accept_language()

close

Convenience method to stop the browser session.

browser.close() -> None

Browser Operations

navigate

Navigate to a URL with optional timeout.

browser.navigate(url, timeout_ms) -> None

Parameters:

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

load_html

Load HTML content directly into the browser.

browser.load_html(url, html) -> None

Parameters:

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

click_selector

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

browser.click_selector(selector) -> None

Parameters:

  • selector: CSS selector for the element

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

click_selector_in_frame

Click an element using CSS selector inside a specific frame.

browser.click_selector_in_frame(frame_id, selector) -> None

Parameters:

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

fill_input

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

browser.fill_input(selector, value) -> None

Parameters:

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

fill_input_in_frame

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

browser.fill_input_in_frame(frame_id, selector, value) -> None

Parameters:

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

select_option

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

browser.select_option(selector, option) -> None

Parameters:

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

select_option_in_frame

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

browser.select_option_in_frame(frame_id, selector, option) -> None

Parameters:

  • frame_id: 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) -> None

Parameters:

  • text: Text to type into the focused element

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

type_in_frame

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

browser.type_in_frame(frame_id, text) -> None

Parameters:

  • frame_id: 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.

move_mouse_to_selector

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.move_mouse_to_selector(selector) -> Tuple[int, int]

Parameters:

  • selector: CSS selector for the element

Returns:

  • x: X coordinate
  • y: Y coordinate

move_mouse_to_selector_in_frame

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

browser.move_mouse_to_selector_in_frame(frame_id, selector) -> Tuple[int, int]

Parameters:

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

Returns:

  • x: X coordinate
  • y: Y coordinate

press_position

Press mouse at a specific coordinate.

browser.press_position(x, y) -> None

Parameters:

  • x: X coordinate
  • y: Y coordinate

release_position

Release mouse at a specific coordinate.

browser.release_position(x, y) -> None

Parameters:

  • x: X coordinate
  • y: Y coordinate

JavaScript Execution

evaluate

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

browser.evaluate(expression) -> EvaluateResult

Parameters:

  • expression: JavaScript expression to execute

Returns:

  • EvaluateResult: Result of the JavaScript expression

evaluate_in_frame

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

browser.evaluate_in_frame(expression, frame_id) -> EvaluateResult

Parameters:

  • expression: JavaScript expression to execute
  • frame_id: 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 (wait_for_...): Search only in the page's top frame (ROOT_FRAME)
  • Global methods (wait_for_..._global): Search across all frames globally
  • Frame-specific methods (wait_for_..._in_frame): Search only in a specific frame

wait_for_selector

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

browser.wait_for_selector(selector, timeout_ms) -> None

Parameters:

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

wait_for_selector_global

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

browser.wait_for_selector_global(selector, timeout_ms) -> str

Parameters:

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

Returns:

  • str: Frame ID where the selector was found

wait_for_expression

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

browser.wait_for_expression(expression, timeout_ms) -> None

Parameters:

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

wait_for_expression_global

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

browser.wait_for_expression_global(expression, timeout_ms) -> str

Parameters:

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

Returns:

  • str: Frame ID where the expression returned true

wait_for_any_selector

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

browser.wait_for_any_selector(selectors, timeout_ms) -> int

Parameters:

  • selectors: List of CSS selectors to wait for
  • timeout_ms: Timeout in milliseconds

Returns:

  • int: Index of the first matching selector

wait_for_any_selector_global

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

browser.wait_for_any_selector_global(selectors, timeout_ms) -> Tuple[int, str]

Parameters:

  • selectors: List of CSS selectors to wait for
  • timeout_ms: Timeout in milliseconds

Returns:

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

wait_for_any_expression

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

browser.wait_for_any_expression(expressions, timeout_ms) -> int

Parameters:

  • expressions: List of JavaScript expressions to wait for
  • timeout_ms: Timeout in milliseconds

Returns:

  • int: Index of the first matching expression

wait_for_any_expression_global

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.wait_for_any_expression_global(expressions, timeout_ms) -> Tuple[int, str]

Parameters:

  • expressions: List of JavaScript expressions to wait for
  • timeout_ms: Timeout in milliseconds

Returns:

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

wait_for_selector_in_frame

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

browser.wait_for_selector_in_frame(frame_id, selector, timeout_ms) -> str

Parameters:

  • frame_id: 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
  • timeout_ms: Timeout in milliseconds

Returns:

  • str: Frame ID where the selector was found

wait_for_expression_in_frame

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

browser.wait_for_expression_in_frame(frame_id, expression, timeout_ms) -> str

Parameters:

  • frame_id: 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
  • timeout_ms: Timeout in milliseconds

Returns:

  • str: Frame ID where the expression returned true

wait_for_any_selector_in_frame

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

browser.wait_for_any_selector_in_frame(frame_id, selectors, timeout_ms) -> Tuple[int, str]

Parameters:

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

Returns:

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

wait_for_any_expression_in_frame

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.wait_for_any_expression_in_frame(frame_id, expressions, timeout_ms) -> Tuple[int, str]

Parameters:

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

Returns:

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

Frame Management

get_frames

Get all available frame IDs.

browser.get_frames() -> List[str]

Returns:

  • List[str]: List of frame IDs

get_frame_tree

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

browser.get_frame_tree() -> FrameTree | None

Returns:

  • FrameTree | None: Frame tree structure

Network Operations

wait_for_request

Wait for a specific network request.

browser.wait_for_request(url, abort, timeout_ms) -> Request

Parameters:

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

Returns:

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

wait_for_response

Wait for a specific network response.

browser.wait_for_response(url, timeout_ms) -> Response

Parameters:

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

Returns:

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

wait_for_any_request

Wait for any of multiple network requests.

browser.wait_for_any_request(url_patterns, abort_flags, timeout_ms) -> Tuple[int, Request]

Parameters:

  • url_patterns: List of URL patterns to wait for
  • abort_flags: List of abort flags corresponding to each URL pattern
  • timeout_ms: Timeout in milliseconds

Returns:

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

wait_for_any_response

Wait for any of multiple network responses.

browser.wait_for_any_response(url_patterns, timeout_ms) -> Tuple[int, Response]

Parameters:

  • url_patterns: List of URL patterns to wait for
  • timeout_ms: Timeout in milliseconds

Returns:

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

modify_request

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

browser.modify_request(url_pattern, timeout_ms, modifications, body) -> Request

Parameters:

  • url_pattern: URL pattern to match
  • timeout_ms: Timeout in milliseconds
  • modifications: List of header modifications
  • body: Optional request body override

Returns:

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

set_block_list

Set URL patterns to block from loading.

browser.set_block_list(patterns) -> None

Parameters:

  • patterns: List of URL patterns supporting wildcard (*).

Cookie Management

get_cookies

Retrieve cookies for the current session.

browser.get_cookies() -> List[Cookie]

Returns:

  • List[Cookie]: List of cookies

set_cookies

Set cookies for the current session.

browser.set_cookies(cookies) -> None

Parameters:

  • cookies: List of cookies to set

clear_cookies

Clear all cookies for the current session.

browser.clear_cookies() -> None

Captcha Solving

solve_captcha

Attempt to solve supported captchas on the page.

browser.solve_captcha(timeout_ms, retry_amount=0) -> str

Parameters:

  • timeout_ms: Timeout in milliseconds
  • retry_amount: Number of retries for captcha solving

Returns:

  • str: Empty string if solved, error message if failed