Browser Actions

Browser Actions gives you full control over the sequence of actions performed in the browser, ensuring predictable and repeatable results. You manually specify each step like click, scroll, wait, or type. Common uses:

Load more content: Click “Show more” buttons or scroll to reveal additional items.
Set filters: Select dropdowns, checkboxes, or date ranges to refine displayed data.
Submit searches: Enter search terms and submit forms to access results pages.
Trigger lazy-loaded data: Scroll to load images, products, or infinite feeds.

When to use

Use Browser Actions when you need:

Predictable execution: Same steps run every time
Full control: Specify exact actions and sequences
Fast performance: No AI inference overhead

Browser Action flows may break when page structure or selectors change. Monitor and update your flows as needed.

Parameters

render - Required

render

boolean

default:"false"

required

Must be set to true to use browser actions. This enables the browser to execute JavaScript and perform interactions.Browser actions only work when the page is rendered in a real browser environment.

Example:

"render": true

browser_actions

array

A list of actions to perform in sequence on the page. Each action is an object specifying what to do (click, scroll, wait, type, etc.).Actions execute in order - the second action waits for the first to complete, and so on.Global timeout: All actions must complete within 240 seconds total.Available actions:

goto - Navigate to a different URL
wait - Pause for a specified duration
wait_for_element - Wait for an element to appear
click - Click an element
press - Press a keyboard key (Enter, Tab, Escape, etc.)
fill - Type or paste text into an input field
scroll - Scroll the page by pixels or to an element
auto_scroll - Automatically scroll to load lazy content
screenshot - Capture a screenshot
get_cookies - Extract cookies from the page
fetch - Make HTTP requests from the browser context

Each action has specific parameters detailed in the sections below.

Example:

"browser_actions": [
  {
    "fill": {
      "selector": "input[type='search']",
      "value": "laptops"
    }
  },
  {
    "click": {
      "selector": "button[type='submit']"
    }
  },
  {
    "wait": "2s"
  }
]

All browser actions execute sequentially within a global 240-second timeout. If any action fails, the entire flow stops unless marked as optional.

Usage

Navigate to URL

Navigate to a different URL during the browser session.Parameters:Direct form - Pass URL as a string:

goto (required) - URL to navigate to

Extended form - Use object with options:

url (required) - URL to navigate to (string)
timeout (optional) - Maximum wait time in milliseconds (number, default: 30000)
referer (optional) - HTTP referer header to send (string)
wait_until (optional) - Navigation wait condition: 'load' (default), 'domcontentloaded', 'networkidle', or 'commit'

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - simple navigation
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "goto": "https://www.example.com/products"  # Navigate to products page
        }
    ]
})

# Extended form - with wait condition
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "goto": {
                "url": "https://www.example.com/products",
                "wait_until": "networkidle",
                "timeout": 5000,
                "referer": "https://www.google.com"
            }
        }
    ]
})

print(result)

Wait (delay)

Add a delay between actions to simulate human behavior or allow elements to load.Parameters:Direct form - Pass duration as a string:

wait (required) - Duration string (e.g., “2s”, “500ms”, “1.5s”)

Extended form - Use object with options:

duration (required) - Duration string (e.g., “2s”, “500ms”, “1.5s”)
required (optional) - Set to false to make this step optional (boolean, default: true)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - simple delay
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "wait": "2s"  # Wait for 2 seconds
        }
    ]
})

# Extended form - with options
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "wait": {
                "duration": "500ms",
                "required": False
            }
        }
    ]
})

Wait for selector

Wait for DOM elements to appear on the page.Parameters:Direct form - Pass single selector or array of selectors:

wait_for_element (required) - CSS selector string or array of selectors to wait for (any one matching triggers success)

Extended form - Use object with options:

selector (required) - CSS selector string or array of selectors to wait for
timeout (optional) - Maximum time in milliseconds to wait (number, default: 30000)
visible (optional) - Whether element must be visible (boolean, default: true)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - wait for single element
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "wait_for_element": "#submit-button"
        }
    ]
})

# Direct form - wait for multiple elements
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "wait_for_element": ["#element1", ".class2"]
        }
    ]
})

# Extended form - with options
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "wait_for_element": {
                "selector": "#element",
                "timeout": 30000,
                "visible": False
            }
        }
    ]
})

print(result)

Click

Click on an element by selector or at specific coordinates.Parameters:Direct form - Pass CSS selector as string:

click (required) - CSS selector string

Extended form (selector mode) - Use object with selector options:

selector (required) - CSS selector of element to click (string)
timeout (optional) - Maximum time to wait for element (Duration string, default: ”30s”)
visible (optional) - Whether element must be visible (boolean, default: true)
delay (optional) - Delay before clicking (Duration string, default: “0ms”)
scroll (optional) - Whether to scroll element into view (boolean, default: true)
count (optional) - Number of times to click (number, default: 1)
steps (optional) - Mouse movement steps for granular control (number, advanced)
strategy (optional) - Mouse movement strategy for behavioral simulation (advanced)
required (optional) - Set to false to make this step optional (boolean, default: true)

Extended form (coordinates mode) - Click at specific coordinates:

x (required) - X coordinate (horizontal position, number)
y (required) - Y coordinate (vertical position, number)
relative_to (optional) - CSS selector to make coordinates relative to this element (string)
timeout (optional) - Maximum time for the click operation (Duration string, default: ”15s”)
delay (optional) - Delay before clicking (Duration string, default: “0ms”)
count (optional) - Number of times to click (number, default: 1)
steps (optional) - Mouse movement steps for granular control (number, advanced)
required (optional) - Set to false to make this step optional (boolean, default: true)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - simple click by selector
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "click": "button.submit"  # Click element matching selector
        }
    ]
})

# Extended form (selector mode) - with options
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "click": {
                "selector": "button.load-more",
                "timeout": "20s",
                "delay": "500ms",
                "scroll": True,
                "visible": True,
                "count": 2  # Double-click
            }
        }
    ]
})

# Extended form (coordinates mode) - click at specific position
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "click": {
                "x": 100,
                "y": 200,
                "delay": "300ms"
            }
        }
    ]
})

# Coordinates relative to element
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "click": {
                "x": 10,
                "y": 10,
                "relative_to": "#container"  # Click 10px from top-left of container
            }
        }
    ]
})

print(result)

Press

Press a keyboard key like Enter, Tab, Escape, or arrow keys.Parameters:Direct form - Pass key name as a string:

press (required) - Key name to press (e.g., “Enter”, “Tab”, “Escape”, “ArrowDown”)

Extended form - Use object with options:

key (required) - Key name to press (string)
delay (optional) - Delay in milliseconds before pressing (number, default: 0)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - press Enter key
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "press": "Enter"  # Press Enter key
        }
    ]
})

# Extended form - press with delay
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "press": {
                "key": "Tab",
                "delay": 500
            }
        }
    ]
})

print(result)

Fill

Fill an input field with text. Supports both typing (character-by-character) and pasting (instant) modes.Parameters:Extended form only - No direct form available:

selector (required) - CSS selector of the input element (string)
value (required) - Text value to fill (string)
mode (optional) - Fill mode: 'type' for character-by-character (default), 'paste' for instant (string)
timeout (optional) - Maximum time to wait for element in milliseconds (number, default: 30000)
typing_interval (optional) - Interval between keystrokes in milliseconds when typing (number, default: 100, min: 10, max: 1000)
click_on_element (optional) - Whether to click on element to focus it (boolean, default: true)
scroll (optional) - Whether to scroll element into view (boolean, default: true)
visible (optional) - Whether element must be visible (boolean, default: true)
delay (optional) - Delay in milliseconds before filling (number, default: 0)
mouse_movement_strategy (optional) - Mouse movement strategy for behavioral simulation (advanced)
typing_strategy (optional) - Typing strategy for behavioral simulation (advanced)
required (optional) - Set to false to make this step optional (boolean, default: true)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Type mode (default, character-by-character)
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "fill": {
                "selector": "input[name='search']",
                "value": "eggplant",
                "mode": "type",  # Default mode
                "typing_interval": 100,  # 100ms between keystrokes
                "click_on_element": True,
                "scroll": True
            }
        }
    ]
})

# Paste mode (instant, faster)
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "fill": {
                "selector": "textarea",
                "value": "Long text content...",
                "mode": "paste",  # Instant paste
                "timeout": 30000
            }
        }
    ]
})

# Fill with options
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "fill": {
                "selector": "input",
                "value": "text",
                "scroll": True,
                "delay": 500,
                "typing_interval": 150,
                "visible": True
            }
        }
    ]
})

print(result)

Scroll

Scroll the page by pixels, to a position, or to an element.Parameters:Direct form - Pass number or string:

scroll: 500 - Scroll Y pixels (number, positive = down, negative = up)
scroll: "bottom" - Scroll to bottom of page (string)
scroll: "#comments" - Scroll to element matching selector (string)

Extended form - Use object with options:

y (optional) - Vertical scroll distance in pixels (number, default: 0)
x (optional) - Horizontal scroll distance in pixels (number, default: 0)
to (optional) - CSS selector to scroll to (string, alternative to x/y)
container (optional) - CSS selector of container element to scroll within (string)
visible (optional) - Whether element must be visible when scrolling to it (boolean, default: true)
required (optional) - Set to false to make this step optional (boolean, default: true)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - scroll down 500px
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "scroll": 500  # Scroll down 500 pixels
        }
    ]
})

# Direct form - scroll up 200px
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "scroll": -200  # Scroll up 200 pixels
        }
    ]
})

# Direct form - scroll to bottom
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "scroll": "bottom"  # Scroll to page bottom
        }
    ]
})

# Direct form - scroll to element
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "scroll": "#comments"  # Scroll to comments section
        }
    ]
})

# Extended form - scroll by pixels
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "scroll": {
                "x": 100,
                "y": 500
            }
        }
    ]
})

# Extended form - scroll to element in container
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "scroll": {
                "to": "#target",
                "container": "#modal",
                "visible": True
            }
        }
    ]
})

print(result)

Auto scroll

Automatically scroll the page to load dynamic content (infinite scroll). Continuously scrolls until content stops loading or timeout is reached.Parameters:Direct form - Pass boolean or number:

auto_scroll: true - Use default settings
auto_scroll: 30000 - Max duration in milliseconds

Extended form - Use object with options:

max_duration (optional) - Maximum duration in milliseconds to scroll (number, default: 25000)
delay_after_scroll (optional) - Delay in milliseconds between scroll steps (number, default: 200)
step_size (optional) - Pixels to scroll per step (number, defaults to viewport height)
click_selector (optional) - CSS selector to click before scrolling (string, e.g., “Load More” button)
container (optional) - CSS selector of container element to scroll within (string)
idle_timeout (optional) - Stop scrolling after this many milliseconds of no new content (number, default: 7000)
pause_on_selector (optional) - Pause scrolling if this selector appears above the cursor position (string)
required (optional) - Set to false to make this step optional (boolean, default: true)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - boolean (use defaults)
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "auto_scroll": True  # Auto scroll with default settings
        }
    ]
})

# Direct form - number (max duration)
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "auto_scroll": 30000  # Auto scroll for max 30 seconds
        }
    ]
})

# Extended form - with options
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "auto_scroll": {
                "max_duration": 30000,
                "container": "#feed",
                "click_selector": ".load-more",
                "delay_after_scroll": 500,
                "idle_timeout": 7000
            }
        }
    ]
})

print(result)

Auto scroll continuously scrolls the page until idle_timeout milliseconds pass with no new content appearing, or until max_duration is reached. Use click_selector to handle “Load More” buttons.

Capture screenshot

Capture a screenshot of the page and return as base64-encoded image.Parameters:Direct form - Pass boolean to capture full page screenshot:

screenshot (required) - Set to true to capture full page PNG screenshot

Extended form - Use object with options:

full_page (optional) - Capture full scrollable page (boolean, default: true)
format (optional) - Image format: 'png' (default), 'jpeg', or 'webp'
quality (optional) - Image quality for jpeg/webp (number, 0-100, default: 90)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - full page PNG screenshot
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "screenshot": True
        }
    ]
})

# Extended form - with options
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "screenshot": {
                "full_page": False,
                "format": "jpeg",
                "quality": 90
            }
        }
    ]
})

print(result)

Collect cookies

Retrieve all cookies set in the browser for the current page.Parameters:Direct form - Pass boolean to get all cookies:

get_cookies (required) - Set to true to retrieve all cookies

Extended form - Use object with options:

domain (optional) - Domain filter for cookies (string, e.g., “.example.com”)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - get all cookies
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "get_cookies": True
        }
    ]
})

# Extended form - with domain filter
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "get_cookies": {
                "domain": ".example.com"
            }
        }
    ]
})

print(result)

Execute HTTP requests

Make HTTP requests from the browser context and return the response.Parameters:Direct form - Pass URL as a string:

fetch (required) - URL for the HTTP request (GET method)

Extended form - Use object with options:

url (required) - URL to request (string)
method (optional) - HTTP method: 'GET' (default), 'POST', 'PUT', 'DELETE', 'PATCH', etc.
headers (optional) - HTTP headers to send as key-value object
body (optional) - Request body as string (for POST, PUT, PATCH)
timeout (optional) - Maximum time in milliseconds to wait for response (number, default: 15000)

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

# Direct form - simple GET request
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "fetch": "https://api.example.com/data"  # Simple GET request
        }
    ]
})

# Extended form - POST with headers and body
result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "fetch": {
                "url": "https://api.example.com/submit",
                "method": "POST",
                "headers": {
                    "Content-Type": "application/json"
                },
                "body": '{"key": "value"}',
                "timeout": 15000
            }
        }
    ]
})

print(result)

The first fetch in a browser_actions is free. Starting from the second request, each additional fetch is billed as a VX6 request.

Chaining actions

You can chain multiple actions together in the browser_actions array. They execute sequentially.

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract({
    "url": "https://www.example.com",
    "render": True,
    "browser_actions": [
        {
            "fill": {
                "selectors": ["input[type='search']"],
                "text": "laptop"
            }
        },
        {
            "wait": "1s"
        },
        {
            "click": {
                "selectors": ["button[type='submit']"]
            }
        },
        {
            "wait_for_element": {
                "selector": ".results",
                "timeout": 5000
            }
        }
    ]
})

print(result)

Example response

When browser actions complete successfully, you’ll receive the final page state along with any data captured. The response includes:

data: All related extacted data
- data.html: Final DOM state after all actions
- data.screenshot: Page screenshot if used
- data.cookies: Collected cookies if get_cookies was used by order
- data.fetch: HTTP response if fetch was used by order
metadata: Execution details including task id, driver used, execution time and more
- metadata.browser_actions: The browser actions results per step

{
  "url": "https://www.example.com/",
  "task_id": "b1fa7943-cba5-4ec2-a88c-4d2d6799c794",
  "status": "success",
  "data": {
    "html": "<!DOCTYPE html><html>...</html>",
    "screenshot": "base64_encoded_image_data",
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123xyz",
        "domain": ".example.com",
        "path": "/",
        "expires": 1735689600,
        "httpOnly": true,
        "secure": true
      }
    ],
	"fetch":[
	  {
		"status": 200,
		"duration": 235,
		"method":"POST",
		"url":"https://api.example.com/submit",
		"headers":{},
		"body":"..."
	  }
	]
  },
  "metadata": {
      "query_time": "2026-02-08T22:00:36.132Z",
      "query_duration": 1877,
      "response_parameters": {
          "input_url": "https://www.example.com/"
      },
      "driver": "vx6"
  },
  "status_code": 200
}

Best practices

Use required parameter for optional steps

Make non-critical steps optional:

# ✅ Continue even if optional element isn't found
browser_actions = [
    {
        "click": {
            "selectors": [".cookie-banner button"],
            "required": False  # Don't fail if banner doesn't exist
        }
    },
    {
        "click": {
            "selectors": [".submit-button"],
            "required": True  # This is critical
        }
    }
]

# ❌ Fail entire request if cookie banner isn't found
browser_actions = [
    {
        "click": {
            "selectors": [".cookie-banner button"]
            # required defaults to True
        }
    }
]

Chain actions with appropriate waits

Add delays between actions:

# ✅ Wait for content to load between actions
browser_actions = [
    {
        "click": {
            "selectors": ["button.load-more"]
        }
    },
    {
        "wait": "2s"  # Wait for new content to load
    },
    {
        "wait_for_element": {
            "selector": ".new-content"
        }
    }
]

# ❌ No wait - may act on stale content
browser_actions = [
    {
        "click": {
            "selectors": ["button.load-more"]
        }
    },
    {
        "click": {
            "selectors": [".new-content button"]  # May not exist yet
        }
    }
]

Use specific selectors

Be precise with CSS selectors:

# ✅ Specific selector
selector = "button[data-testid='submit-form']"

# ✅ Unique class or ID
selector = "#unique-submit-button"

# ❌ Too generic - may match wrong element
selector = "button"

# ❌ Fragile - breaks with style changes
selector = ".btn.btn-primary.btn-lg.mt-4"

Optimize auto scroll parameters

Set appropriate scroll limits:

# ✅ Controlled scrolling with limits
auto_scroll = {
    "max_duration": 10000,  # 10 seconds max
    "idle_timeout": 3000,  # Stop if no change for 3s
    "delay_after_scroll": 500,  # Wait between scrolls
    "click_selector": ".load-more"  # Handle load more buttons
}

# ❌ Excessive scrolling - slow and costly
auto_scroll = {
    "max_duration": 60000,  # 60 seconds - too long
    "delay_after_scroll": 100  # Too fast - may miss content
}example

Introduction

Web Tools

Agentic

When to use

Parameters

Usage

Example response

Best practices

Use required parameter for optional steps

Chain actions with appropriate waits

Use specific selectors

Optimize auto scroll parameters

Introduction

Web Tools

Agentic

​When to use

​Parameters

​Usage

​Example response

​Best practices

​Use required parameter for optional steps

​Chain actions with appropriate waits

​Use specific selectors

​Optimize auto scroll parameters

When to use

Parameters

Usage

Example response

Best practices

Use required parameter for optional steps

Chain actions with appropriate waits

Use specific selectors

Optimize auto scroll parameters