Browser Actions
Automate browser interactions like clicking, typing, scrolling, and waiting using the browserActions array.
Automate interactions with web pages by specifying a sequence of typed actions in the
browserActionsarray of your request payload.
Command
Browser actions are passed as the browserActions array on any request.get or request.post call.
Parameters
All actions share a common set of top-level properties.
| Parameter | Type | Required | Description |
|---|---|---|---|
type |
string | Yes | The action type (see Action Types below). |
when |
string | No | Lifecycle phase to run this action. Defaults to "afterload". |
ignoreErrors |
boolean | No | If true, errors in this action will not stop execution. |
timeout |
number | No | Timeout in milliseconds. Default 60000. |
Execution Lifecycle
Browser actions run at specific points during the request lifecycle. Use the when property to control when each action executes. If when is omitted it defaults to "afterload".
Lifecycle Phases (in order)
Phase Details
| Phase | When it runs | Use case |
|---|---|---|
beforelaunch |
Before any navigation. No page context yet. | Setting up browser state, pre-flight actions |
beforeload |
After cookies are added, before GET/POST navigation | Pre-navigation setup, adding localStorage |
afterload |
After page navigation completes | Main page interactions — filling forms, clicking buttons, extracting data |
Additional lifecycle phases used by authorized verification workflows are documented on the login-gated Verification Flow Handling guide — sign in with your Scrappey account to view them.
Each action in the browserActions array is tagged with a when phase. The engine loops through the array multiple times — once per phase — and only runs actions whose when matches the current phase. Actions within the same phase execute in order.
When actions are nested inside if.then, if.or, or while.then, the when property of nested actions is ignored — they run immediately when the parent action executes. Only top-level actions in the browserActions array are filtered by when.
Action Types
`click` - Click an Element
Clicks on an element using CSS selector. See the dedicated Click Action guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
cssSelector |
string | Yes | CSS selector of element to click. |
wait |
number | No | Wait time in seconds after clicking. |
waitForSelector |
string | No | Wait for this selector to appear after click. |
direct |
boolean | No | Use direct click instead of cursor simulation. |
Example:
`type` - Type Text into Input
Types text into an input field with configurable delays between keystrokes. See the dedicated Type Action guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
cssSelector |
string | Yes | CSS selector of input element. |
text |
string | Yes | Text to type. |
wait |
number | No | Wait time in seconds after typing. |
direct |
boolean | No | Use direct typing instead of cursor simulation. |
Example:
`goto` - Navigate to URL
Navigates the browser to a new URL. See the dedicated Go To guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | URL to navigate to. |
wait |
number | No | Wait time in seconds after navigation. |
Example:
`wait` - Wait for Duration
Pauses execution for a specified time. See the dedicated Wait guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
wait |
number | Yes | Wait time in seconds. |
Example:
`wait_for_selector` - Wait for Element
Waits for an element to appear in the DOM. See the dedicated Wait For Selector guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
cssSelector |
string | Yes | CSS selector to wait for. |
timeout |
number | No | Timeout in ms. Default 60000. |
Example:
`wait_for_function` - Wait for JavaScript Condition
Waits until a JavaScript expression returns truthy. See the dedicated Wait For Function guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
string | Yes | JavaScript code that returns truthy when done. |
timeout |
number | No | Timeout in ms. Default 60000. |
Example:
`wait_for_load_state` - Wait for Page State
Waits for a specific page load state. See the dedicated Wait For Load State guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
waitForLoadState |
string | Yes | "domcontentloaded", "networkidle", or "load". |
Example:
`wait_for_cookie` - Wait for Cookie
Waits for a specific cookie to be set.
| Parameter | Type | Required | Description |
|---|---|---|---|
cookieName |
string | Yes | Name of the cookie to wait for. |
cookieValue |
string | No | Expected value of the cookie. |
cookieDomain |
string | No | Domain the cookie should be set on. |
pollIntervalMs |
number | No | Poll interval. Default 200 ms. |
timeout |
number | No | Timeout in ms. Default 60000. |
Example:
`execute_js` - Execute JavaScript
Executes JavaScript code on the page. Results are stored in the javascriptReturn array. See the dedicated Execute Javascript guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
string | Yes | JavaScript code to execute. |
dontReturnValue |
boolean | No | If true, the return value is not captured. |
Example:
Access results in subsequent actions via {javascriptReturn[0]}.
`scroll` - Scroll Page/Element
Scrolls to an element or the bottom of the page. See the dedicated Scroll guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
cssSelector |
string | No | Element to scroll to. If omitted, scrolls to bottom. |
repeat |
number | No | Number of times to repeat the scroll. |
delayMs |
number | No | Delay between scrolls. Default 100 ms. |
Example:
`hover` - Hover Over Element
Hovers the mouse over an element.
| Parameter | Type | Required | Description |
|---|---|---|---|
cssSelector |
string | Yes | CSS selector of element to hover. |
timeout |
number | No | Timeout in ms. |
Example:
`keyboard` - Press Keyboard Key
Simulates keyboard key presses. See the dedicated Keyboard guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
value |
string | Yes | Key to press (see supported values below). |
cssSelector |
string | No | Element to focus first (required for clear). |
wait |
number | No | Wait time in seconds after pressing. |
waitForSelector |
string | No | Wait for selector after pressing. |
Supported values: tab, enter, space, arrowdown, arrowup, arrowleft, arrowright, backspace, clear
Example:
`dropdown` - Select Dropdown Option
Selects an option from a dropdown/select element. See the dedicated Dropdown Action guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
cssSelector |
string | Yes | CSS selector of select element. |
index |
number | No | Option index to select. |
value |
string | No | Option value to select. |
wait |
number | No | Wait time in seconds after selection. |
waitForSelector |
string | No | Wait for selector after selection. |
Either index or value is required.
Example:
`switch_iframe` - Switch to iFrame
Switches context to an iframe for subsequent actions.
| Parameter | Type | Required | Description |
|---|---|---|---|
cssSelector |
string | Yes | CSS selector of the iframe. |
Example:
`set_viewport` - Set Browser Viewport
Changes the browser viewport size.
| Parameter | Type | Required | Description |
|---|---|---|---|
width |
number | No | Viewport width. Default 1280. |
height |
number | No | Viewport height. Default 1024. |
wait |
number | No | Wait time in seconds after setting. |
Example:
`if` - Conditional Execution
Executes actions conditionally based on a JavaScript condition. See the dedicated Conditional guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
condition |
string | Yes | JavaScript condition to evaluate. |
then |
array | No | Actions to run if condition is true. |
or |
array | No | Actions to run if condition is false. |
Example:
`while` - Loop Execution
Loops actions while a condition is true. See the dedicated While Loop guide.
| Parameter | Type | Required | Description |
|---|---|---|---|
condition |
string | Yes | JavaScript condition to evaluate. |
then |
array | Yes | Actions to run each iteration. |
maxAttempts |
number | No | Maximum iterations (prevents infinite loops). |
Example:
`solve_captcha` - Verification Flow Handling
Handles interactive verification steps that can appear during an authorized browser workflow, so a permitted session can continue. The action takes a captcha type and an optional captchaData configuration object.
The supported verification types and the full captchaData parameter reference are documented on the login-gated Verification Flow Handling guide — sign in with your Scrappey account to view them. Only use verification handling within authorized workflows where you have a lawful basis to proceed.
Example:
Authenticated login
Some workflows need to start from an already-authenticated session. Token-based login actions are documented on the login-gated Authenticated Login Flow guide; sign in with your Scrappey account to view the parameters and example. Only use them to automate accounts you own or are authorized to access.
`remove_iframes` - Remove All iFrames
Removes all iframes from the page (experimental). No additional properties required.
Example:
`click_and_hold` - Click and Hold
Note: This action is not yet implemented.
Example
Using JavaScript Return Values
Results from execute_js are stored in the javascriptReturn array and can be referenced in subsequent actions:
Full Login Flow
Notes
Sequencing actions after a verification step
Actions that must run only after an authorized verification step completes use a dedicated lifecycle phase. That phase, and a worked example of submitting a form once a verification token is ready, are documented on the login-gated Verification Flow Handling guide — sign in with your Scrappey account to view them.