WebBrowserBot Command Reference

Sessions and Profiles

• new_session opens a browser session. Args: profile (required), provider (optional, omit for proxyless). Returns session_id and data: {profile, provider}.
• close_session closes one session. Args: session_id. Returns {closed: true}.
• close_all closes every session and stops Playwright. Returns {closed: true}.
• list_sessions lists open sessions with their profile, provider, tabs, active tab, and URL.
• create_profile makes a fingerprint profile without opening a browser. Args: name (required), identity (optional object). Returns {profile, fingerprint}.
• get_profile reads a profile. Args: profile (required). Returns {identity, fingerprint, has_browser_state}.
• update_profile patches a profile. Args: profile (required), fields (required object). Returns {profile, updated}.
• save_profile persists the session's cookies and storage into its profile. Args: session_id. Returns {profile, saved: true}.
• list_profiles lists profiles on disk.

Navigation

• goto loads a URL. Args: session_id, url (required), wait_until (optional, default "load"), timeout (optional ms, default 30000). Returns {title, url, html}, plus a notice if the sticky IP rotated during the request.
• back, forward, refresh move through history and reload. Args: session_id. Returns {title, url, html}.

Interaction

• click clicks an element by CSS selector, moving the mouse to the element center with a small human offset first. Args: session_id, selector (required). Returns {title, url, html}.
• type types text character by character with human-like delays. Args: session_id, selector (required), text, clear (optional bool). Returns {typed}.
• press presses a key on the focused element. Args: session_id, key (required, e.g. "Enter"). Returns {pressed}.
• select chooses an option in a select element. Args: session_id, selector (required), value (required). Returns {selected}.
• hover hovers an element. Args: session_id, selector (required). Returns {hovered}.
• scroll scrolls the page or to an element. Args: session_id, and either selector or direction ("up"/"down", default "down") plus amount (px, default 500). Returns {scrolled: true}.
• mouse_click clicks at raw page coordinates. Args: session_id, x (required), y (required). Returns {clicked_at, url, title}.
• wait waits for a selector to appear. Args: session_id, selector (required), timeout (optional ms, default 30000). Returns {found}.

Reading

• read returns trimmed HTML with hidden nodes, styles, inline styles, and data-URIs removed. Args: session_id. Returns {title, url, html}.
• read_full returns the full raw HTML. Args: session_id. Returns {title, url, html}.
• text returns the visible text (the page body innerText). Best for JS-rendered pages. Args: session_id. Returns {title, url, text}.
• screenshot saves a PNG to the screenshots directory. Args: session_id, full_page (optional bool, default true). Returns {path, filename}.
• execute_js runs JavaScript in the page and returns the result. Args: session_id, script (required). Returns {result}.

Tabs

• new_tab opens a tab. Args: session_id, url (optional). Returns {tab, url}.
• switch_tab focuses a tab. Args: session_id, tab (index, required). Returns {tab, url, title}.
• list_tabs lists tabs. Args: session_id. Returns {tabs}.
• close_tab closes a tab. Args: session_id, tab (index, required). Returns {closed_tab, tabs_remaining}.

Frames

• list_frames lists frames on the page. Args: session_id. Returns {frames, count}.
• click_frame clicks a link inside a matching frame. Args: session_id, frame_match (required substring of the frame name or URL), selector (optional, default "a[href]"). Returns {clicked_href, current_url, current_title, tabs}.

Timing

• sleep pauses. Args: ms (default 1000, clamped 100 to 30000). Returns {slept_ms}.