browser
browser.add_init_script
browser.add_init_script
Register JavaScript that runs BEFORE the page's own code, at document start, on every page opened afterwards in this identity's context. Use when browser.evaluate is too late — most often to hook window.fetch/XMLHttpRequest and capture a SPA's request bodies, which network_requests cannot show. Does NOT affect already-open pages: add the script first, then browser.open. Cannot be removed once added; it lives until the context is evicted or browser.close is called.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
identity_name | string | no | default _anon |
script | string | yes |
browser.attach_identity
browser.attach_identity
Switch the page's identity by loading saved cookies + storage. Use only when switching identity mid-page; for first navigation, pass identity_name to browser.open instead.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
identity_name | string | yes | |
page_id | string | yes |
browser.attach_meet
browser.attach_meet
Attach to THIS meet's bot browser and return a page_id for its live Google Meet tab. Then use the normal browser.* tools (browser.snapshot to see the page, browser.click to press a control, browser.take_screenshot, browser.evaluate, browser.console_messages, browser.network_requests) with that page_id to inspect why the bot isn't visibly joining (lobby/blocked/admitted) and to recover a stalled join. Call with no arguments from inside a meet.
Arguments
No arguments.
browser.click
browser.click
Click an element. ref is either an aria-ref token from browser.snapshot ('e7') OR a CSS selector ('button.submit'). Prefer the aria-ref token.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
ref | string | yes |
browser.close
browser.close
Close a page opened by browser.open.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes |
browser.console_messages
browser.console_messages
Return console.log/warn/error events captured since the last drain. Filter by level ('log'|'info'|'warning'|'error'|'debug') and/or pattern (regex). Buffer caps at 500 entries; oldest are dropped first. Set clear=false to peek without draining.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
clear | boolean | no | default True |
level | string | null | no | default None |
page_id | string | yes | |
pattern | string | null | no | default None |
browser.drag
browser.drag
Drag one element onto another. source_ref is the element to grab; target_ref is where to drop. Both are CSS selectors. Used for slider captchas, kanban, drag-and-drop uploads.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
source_ref | string | yes | |
target_ref | string | yes |
browser.evaluate
browser.evaluate
Run JavaScript in the page context and return the result. Use for state not in the a11y tree, captcha iframe inspection, DOM events. Expression is either a plain JS value ('document.title') or a zero-arg IIFE ('(() => { … })()'). Inline any runtime values into the expression itself. Result is JSON-serialized; non-serializable values become strings. 256KB cap on output.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
expression | string | yes | |
page_id | string | yes |
browser.file_upload
browser.file_upload
Attach files to an <input type=file>. Pass either local_paths (absolute host paths) or data (list of {name, mime, base64} blobs written to /tmp). 25MB cap per file.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
data | array | null | no | default None |
local_paths | array | null | no | default None |
page_id | string | yes | |
ref | string | yes |
browser.fill
browser.fill
Fill an input or textarea with the given value. ref is either an aria-ref token from browser.snapshot ('e7') OR a CSS selector ('input[name=email]'). Prefer the aria-ref token — it's stable and matches exactly what snapshot returned.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
ref | string | yes | |
value | string | yes |
browser.fill_form
browser.fill_form
Fill multiple form fields in one call. fields is a list of {ref, value} dicts. ref is a CSS selector; value is a string (text) or boolean (checkbox). Saves N round-trips vs calling browser.fill repeatedly.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
fields | array | yes | |
page_id | string | yes |
browser.handle_dialog
browser.handle_dialog
Respond to a pending JS dialog (alert/confirm/prompt). Pass accept=true for OK or false for Cancel. For prompt() dialogs also pass prompt_text. Dialogs are queued at page-open time; returns {pending: false} if none is waiting.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
accept | boolean | yes | |
page_id | string | yes | |
prompt_text | string | null | no | default None |
browser.hover
browser.hover
Hover the mouse over an element (reveals tooltips + hover menus). ref is a CSS selector.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
ref | string | yes |
browser.navigate_back
browser.navigate_back
Navigate back in the page's history (browser back button). Returns the new URL + title.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes |
browser.network_requests
browser.network_requests
List HTTP requests the page made since open or last drain. Optional filters: method (GET/POST/...), url_pattern (regex), status_min (e.g. 400 for errors). Captures up to 200 most recent requests per page.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
clear | boolean | no | default False |
method | string | null | no | default None |
page_id | string | yes | |
status_min | integer | null | no | default None |
url_pattern | string | null | no | default None |
browser.open
browser.open
Open a URL in a remote browser. Saved login cookies are auto-attached when the URL domain matches a claimed browser identity. Pass identity_name to override auto-matching or force a specific identity.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
identity_name | string | null | no | default None |
url | string | yes |
browser.press_key
browser.press_key
Press a keyboard key (e.g., 'Enter', 'Tab', 'Escape', 'ArrowDown') or a single character. Optional ref focuses an element first — aria-ref token from browser.snapshot ('e7') or a CSS selector.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
key | string | yes | |
page_id | string | yes | |
ref | string | null | no | default None |
browser.resize
browser.resize
Resize the page viewport. Useful when a site serves different HTML based on viewport width (mobile vs desktop) or when an anti-bot scores risk by viewport dimensions.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
height | integer | yes | |
page_id | string | yes | |
width | integer | yes |
browser.select_option
browser.select_option
Pick option(s) in a native <select> dropdown. Pass value (matches the option's value attr) OR label (matches its visible text). Lists allowed for multi-select.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
label | string | array | null | no | default None |
page_id | string | yes | |
ref | string | yes | |
value | string | array | null | no | default None |
browser.snapshot
browser.snapshot
Return a YAML aria_snapshot of the page DOM. Each interactive node is tagged with [ref=eN] (e.g. [ref=e7]). Pass that exact token as the ref arg to browser.click / browser.fill / browser.type / browser.press_key. Do NOT pass the role name ('combobox', 'button') as ref — only the eN token. Truncated at 32KB.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes |
browser.tabs
browser.tabs
Manage tabs within the same BrowserContext as page_id. action ∈ {list, switch, close, new}. For list, returns all open tab metadata; for new, returns the new tab's page_id.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
action | string | yes | |
page_id | string | yes | |
tab_id | string | null | no | default None |
url | string | null | no | default None |
browser.take_screenshot
browser.take_screenshot
Capture a PNG screenshot of the page or a specific element. Returns base64-encoded image bytes AND a file_id (persisted in DialogBrain files storage). Pass file_id straight to messages.send(attachment_file_ids=[file_id]) — do NOT call files.upload again. Use sparingly — favor browser.snapshot for structured DOM understanding.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
full_page | boolean | no | default False |
inline_bytes | boolean | no | default False |
page_id | string | yes | |
ref | string | null | no | default None |
browser.type
browser.type
Type text into an element with per-keystroke delay (organic). Each character dispatches keydown/keypress/keyup, unlike browser.fill which replaces .value instantly. Use when the page listens to keystroke events or for typing-speed fingerprint checks. ref is an aria-ref token from browser.snapshot ('e7') or a CSS selector. delay_ms defaults to 50.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
delay_ms | integer | null | no | default 50 |
page_id | string | yes | |
ref | string | yes | |
text | string | yes |
browser.wait_for
browser.wait_for
Wait for a selector to appear OR a navigation URL to match a glob pattern. Provide ref (selector) OR url_pattern (glob).
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
ref | string | null | no | default None |
timeout_ms | integer | no | default 10000 |
url_pattern | string | null | no | default None |