RPC API Reference

Complete reference for all gRPC methods available in the Browser Cloud API. All requests must include session_id and api_key as the first two fields in the request payload.

Navigation

Navigate

Navigate to a URL with optional timeout.

Method: cloudbrowser.BrowserService/Navigate

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "url": "https://example.com",
  "timeout_ms": 30000
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
url (string, required): URL to navigate to
timeout_ms (int32, required): Timeout in milliseconds

Response:

{}

Empty response on success.

LoadHTML

Load HTML content directly into the browser.

Method: cloudbrowser.BrowserService/LoadHTML

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "url": "https://example.com",
  "html": "<html><body>Hello World</body></html>"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
url (string, required): URL to load the HTML content at (emulated)
html (string, required): HTML content to load

Response:

{}

Empty response on success.

JavaScript Execution

Evaluate

Execute JavaScript expression and return the result.

Method: cloudbrowser.BrowserService/Evaluate

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "expression": "document.title",
  "frame_id": ""
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
expression (string, required): JavaScript expression to execute
frame_id (string, optional): Frame ID. Use "" (empty string) or "ROOT_FRAME" to evaluate in the page's top frame, or a specific frame ID to evaluate only in that frame

Response:

{
  "result": "\"Example Page\""
}

result (string): JSON-encoded result of the JavaScript expression

Waiting Operations

WaitForSelector

Wait for an element to appear. Searches across all frames globally if frame_id is empty.

Method: cloudbrowser.BrowserService/WaitForSelector

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "selector": "#my-button",
  "timeout_ms": 30000,
  "frame_id": ""
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
selector (string, required): CSS selector to wait for
timeout_ms (int32, required): Timeout in milliseconds
frame_id (string, optional): Use "" (empty string) to search across all frames globally, "ROOT_FRAME" to search only in the page's top frame, or a specific frame ID to search only in that frame (not children)

Response:

{
  "frame_id": "frame-123"
}

frame_id (string): Frame ID where the selector was found

WaitForExpression

Wait for a JavaScript expression to return true. Searches across all frames globally if frame_id is empty.

Method: cloudbrowser.BrowserService/WaitForExpression

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "expression": "document.readyState === 'complete'",
  "timeout_ms": 30000,
  "frame_id": ""
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
expression (string, required): JavaScript expression to wait for
timeout_ms (int32, required): Timeout in milliseconds
frame_id (string, optional): Use "" (empty string) to search across all frames globally, "ROOT_FRAME" to search only in the page's top frame, or a specific frame ID to search only in that frame (not children)

Response:

{
  "frame_id": "frame-123"
}

frame_id (string): Frame ID where the expression returned true

WaitForAnySelector

Wait for any of multiple selectors to appear. Searches across all frames globally if frame_id is empty.

Method: cloudbrowser.BrowserService/WaitForAnySelector

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "selectors": ["#button1", "#button2", "#button3"],
  "timeout_ms": 30000,
  "frame_id": ""
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
selectors (array of strings, required): Array of CSS selectors to wait for
timeout_ms (int32, required): Timeout in milliseconds
frame_id (string, optional): Use "" (empty string) to search across all frames globally, "ROOT_FRAME" to search only in the page's top frame, or a specific frame ID to search only in that frame (not children)

Response:

{
  "index": 1,
  "frame_id": "frame-123"
}

index (int32): Index of the first matching selector (0-based)
frame_id (string): Frame ID where the selector was found

WaitForAnyExpression

Wait for any of multiple JavaScript expressions to return true. Searches across all frames globally if frame_id is empty.

Method: cloudbrowser.BrowserService/WaitForAnyExpression

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "expressions": [
    "document.getElementById('btn1')",
    "document.getElementById('btn2')"
  ],
  "timeout_ms": 30000,
  "frame_id": ""
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
expressions (array of strings, required): Array of JavaScript expressions to wait for
timeout_ms (int32, required): Timeout in milliseconds
frame_id (string, optional): Use "" (empty string) to search across all frames globally, "ROOT_FRAME" to search only in the page's top frame, or a specific frame ID to search only in that frame (not children)

Response:

{
  "index": 0,
  "frame_id": "frame-123"
}

index (int32): Index of the first matching expression (0-based)
frame_id (string): Frame ID where the expression returned true

Browser Operations

ClickSelector

Click an element using CSS selector. The selector is searched across all frames globally.

Method: cloudbrowser.BrowserService/ClickSelector

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "selector": "#submit-button"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
selector (string, required): CSS selector for the element

Response:

{}

Empty response on success.

FillInput

Fill an input field with a value. The selector is searched across all frames globally.

Method: cloudbrowser.BrowserService/FillInput

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "selector": "#email-input",
  "value": "user@example.com"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
selector (string, required): CSS selector for the input element
value (string, required): Value to fill into the input field

Response:

{}

Empty response on success.

SelectOption

Select an option from a select element. The selector is searched across all frames globally.

Method: cloudbrowser.BrowserService/SelectOption

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "selector": "#country-select",
  "option": "US"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
selector (string, required): CSS selector for the select element
option (string, required): Option value or text to select

Response:

{}

Empty response on success.

Type

Type text into the currently focused element.

Method: cloudbrowser.BrowserService/Type

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "text": "Hello World"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
text (string, required): Text to type into the focused element

Response:

{}

Empty response on success. Note: This method types into whatever element currently has focus. Use ClickSelector or FillInput first to focus an element if needed.

MoveMouseToSelector

Move mouse to an element using CSS selector. Returns the coordinates where the mouse was moved.

Method: cloudbrowser.BrowserService/MoveMouseToSelector

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "selector": "#hover-target"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
selector (string, required): CSS selector for the element

Response:

{
  "x": 150,
  "y": 200
}

x (int32): X coordinate
y (int32): Y coordinate

PressPosition

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

Method: cloudbrowser.BrowserService/PressPosition

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "x": 100,
  "y": 200
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
x (int32, required): X coordinate to press
y (int32, required): Y coordinate to press

Response:

{}

Empty response on success.

ReleasePosition

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

Method: cloudbrowser.BrowserService/ReleasePosition

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "x": 100,
  "y": 200
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
x (int32, required): X coordinate to release
y (int32, required): Y coordinate to release

Response:

{}

Empty response on success.

Frame Management

Many RPC methods accept a frame_id parameter to specify which frame to operate on. Use "" (empty string) to search across all frames globally, "ROOT_FRAME" to target the page's top/main frame only, or a specific frame ID to search only in that frame (not children).

GetFrames

Get all available frame IDs.

Method: cloudbrowser.BrowserService/GetFrames

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key

Response:

{
  "frame_ids": ["frame-1", "frame-2", "frame-3"]
}

frame_ids (array of strings): Array of frame IDs

GetFrameTree

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

Method: cloudbrowser.BrowserService/GetFrameTree

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key

Response:

{
  "frame_tree": {
    "frame_id": "frame-1",
    "pos_x": 0,
    "pos_y": 0,
    "children": [
      {
        "frame_id": "frame-2",
        "pos_x": 10,
        "pos_y": 20,
        "children": []
      }
    ]
  }
}

frame_tree (object): Frame tree structure with frame_id, pos_x, pos_y, and children array

Network Operations

WaitForRequest

Wait for a specific network request.

Method: cloudbrowser.BrowserService/WaitForRequest

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "url": "https://api.example.com/data",
  "abort": false,
  "timeout_ms": 30000
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
url (string, required): URL pattern to wait for
abort (bool, required): Whether to abort the request
timeout_ms (int32, required): Timeout in milliseconds

Response:

{
  "request": {
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [
      {"name": "User-Agent", "value": "Mozilla/5.0..."},
      {"name": "Accept", "value": "application/json"}
    ],
    "body": "",
    "status_code": 0
  }
}

request (object): Request object with method, url, headers array, body, and status_code

WaitForResponse

Wait for a specific network response.

Method: cloudbrowser.BrowserService/WaitForResponse

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "url": "https://api.example.com/data",
  "timeout_ms": 30000
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
url (string, required): URL pattern to wait for
timeout_ms (int32, required): Timeout in milliseconds

Response:

{
  "response": {
    "url": "https://api.example.com/data",
    "headers": [
      {"name": "Content-Type", "value": "application/json"},
      {"name": "Content-Length", "value": "1234"}
    ],
    "body": "{\"data\": \"value\"}",
    "status_code": 200
  }
}

response (object): Response object with url, headers array, body, and status_code

WaitForAnyRequest

Wait for any of multiple network requests.

Method: cloudbrowser.BrowserService/WaitForAnyRequest

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "url_patterns": [
    "https://api.example.com/endpoint1",
    "https://api.example.com/endpoint2"
  ],
  "abort_flags": [false, true],
  "timeout_ms": 30000
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
url_patterns (array of strings, required): Array of URL patterns to wait for
abort_flags (array of bools, required): Array of abort flags corresponding to each URL pattern
timeout_ms (int32, required): Timeout in milliseconds

Response:

{
  "index": 0,
  "request": {
    "method": "GET",
    "url": "https://api.example.com/endpoint1",
    "headers": [],
    "body": "",
    "status_code": 0
  }
}

index (int32): Index of the matching request (0-based)
request (object): Request object

WaitForAnyResponse

Wait for any of multiple network responses.

Method: cloudbrowser.BrowserService/WaitForAnyResponse

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "url_patterns": [
    "https://api.example.com/endpoint1",
    "https://api.example.com/endpoint2"
  ],
  "timeout_ms": 30000
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
url_patterns (array of strings, required): Array of URL patterns to wait for
timeout_ms (int32, required): Timeout in milliseconds

Response:

{
  "index": 1,
  "response": {
    "url": "https://api.example.com/endpoint2",
    "headers": [],
    "body": "{}",
    "status_code": 200
  }
}

index (int32): Index of the matching response (0-based)
response (object): Response object

ModifyRequest

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

Method: cloudbrowser.BrowserService/ModifyRequest

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "url_pattern": "https://api.example.com/*",
  "timeout_ms": 30000,
  "modifications": [
    {
      "name": "Authorization",
      "value": "Bearer token123",
      "action": 0
    },
    {
      "name": "User-Agent",
      "value": "CustomAgent/1.0",
      "action": 1
    }
  ],
  "body": ""
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
url_pattern (string, required): URL pattern to match requests for modification
timeout_ms (int32, required): Timeout in milliseconds
modifications (array of objects, required): Array of header modifications
body (string, optional): New request body (only applies to POST requests)
Header modification actions: 0 = ADD, 1 = EDIT, 2 = REMOVE

Response:

{
  "request": {
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [
      {"name": "Authorization", "value": "Bearer token123"},
      {"name": "User-Agent", "value": "CustomAgent/1.0"}
    ],
    "body": "",
    "status_code": 0
  }
}

request (object): Modified request object

SetBlockList

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

Method: cloudbrowser.BrowserService/SetBlockList

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key",
  "patterns": [
    "https://ads.example.com/*",
    "https://tracking.example.com/*"
  ]
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key
patterns (array of strings, required): Array of URL patterns to block (supports wildcard *)

Response:

{}

Empty response on success.

Cookie Management

GetCookies

Get all browser cookies.

Method: cloudbrowser.BrowserService/GetCookies

Request:

{
  "session_id": "ABC123",
  "api_key": "your-api-key"
}

session_id (string, required): Session ID from the rent response
api_key (string, required): Your API key

Response:

{
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123",
      "domain": ".example.com",
      "path": "/"
    },
    {
      "name": "user_pref",
      "value": "dark_mode",
      "domain": ".example.com",
      "path": "/settings"
    }
  ]
}

cookies (array of objects): Array of cookie objects with name, value, domain, and path

Documentation

RPC API Reference

Navigation

Navigate

LoadHTML

JavaScript Execution

Evaluate

Waiting Operations

WaitForSelector

WaitForExpression

WaitForAnySelector

WaitForAnyExpression

Browser Operations

ClickSelector

FillInput

SelectOption

Type

MoveMouseToSelector

PressPosition

ReleasePosition

Frame Management

GetFrames

GetFrameTree

Network Operations

WaitForRequest

WaitForResponse

WaitForAnyRequest

WaitForAnyResponse

ModifyRequest

SetBlockList

Cookie Management

GetCookies