Create a new stealth browser session and make it current. Returns its id.

    Runs PROXYLESS by default. To use a proxy, pass either proxy_url
    ('http://user:pass@host:port') or proxy_server[+username/password].
    no_proxy=True forces proxyless even if an env/default proxy is configured.

    persistent: keep cookies/localStorage in a profile dir across runs.
    headless: override the configured default (None = use the default).
    humanize: per-session cursor humanization — a float caps cursor-move time in seconds
        (e.g. 0.25 = fast but still humanized), True = default speed, False = off,
        None = use the configured default.
    record_har: capture a full network HAR (export with browser_har_export).
    record_video: record the session to a native .webm (Chromium only); fetch the path with
        browser_video_path. The file is finalized on browser_close_session.
    record_video_width / record_video_height: pin the recording resolution (e.g. 1920 x 1080
        for HD); when omitted Playwright defaults to 800x450.
    har_url_filter: glob to scope what the HAR records (e.g. '**/api/**' or
        '**/students/**') so it excludes login/captcha/static noise; default = all.
    storage_state: path to a saved cookies/localStorage JSON to reload.
    extensions: list of paths to UNPACKED Chromium extension folders to side-load (e.g. a
        captcha-solver or a custom extension). Forces a persistent + headful session
        (Chromium only side-loads extensions that way); the profile persists so the
        extension's own config/login survives.
    Most tools auto-create a default session, so calling this is optional.
    

Path to this session's native video recording (Chromium only).

    Only present when record_video=true was passed to browser_new_session. The .webm is
    finalized when the session closes (browser_close_session); the path is known beforehand.
    

Close a session and free its browser.

List all open sessions with their current url, tab count, and identity.

Navigate to a URL. Returns the page's ARIA snapshot (with [ref=...] handles).

    wait_until: when to consider navigation done —
        'domcontentloaded' (default, fast: DOM parsed) | 'commit' (fastest: response
        started) | 'load' (waits for ALL resources — slow/unreliable on heavy or proxied
        sites) | 'networkidle'. Prefer the default and then browser_wait_for a specific
        element; only use 'load' for simple static pages.
    timeout_ms: max navigation wait; None = the engine's configured navigation timeout.
    Auto-creates a session if none exists.
    

Go back one entry in history. Returns the new page's ARIA snapshot.

Go forward one entry in history. Returns the new page's ARIA snapshot.

Reload the current page. Returns the page's ARIA snapshot.

Switch the active page to the most recently opened popup or new tab.

    Use this after triggering an OAuth / SSO flow (Google Sign-In, GitHub OAuth,
    etc.) or any action that calls window.open() or opens a target=_blank link.
    The tool waits up to timeout_ms for the new window to open, then makes it the
    active page and returns its ARIA snapshot. To go back to the original tab
    afterward, use browser_tabs(action='select', index=0).

Manage tabs. action: list | new | select | close (index for select/close, url optional for new). Returns the resulting tab list.

Capture the page's ARIA accessibility tree with [ref=...] handles.

    This is the primary way to 'see' a page: it lists actionable elements (roles +
    names + refs) without CSS/markup noise. Pass a ref from here to click/type/hover.
    Frame-hosted elements get prefixed refs like 'f1e36' (iframe 1, element 36).
    Shadow DOM elements appear with plain eN refs — the locator engine pierces them.

    enrich=True ALSO appends a DOM map of visible interactive elements, each with a css
    selector usable in the ref slot (browser_click(ref="css=...")). Use it when the ARIA
    tree collapses to bare 'generic' nodes with no usable names/refs (JS-heavy sites).
    

Find VISIBLE interactive elements whose text / placeholder / label / type contains query — the escape hatch when browser_snapshot is all 'generic' (no usable [ref=eN]). Returns a list of matches, each with a css selector you act on via the ref slot, e.g. browser_click(ref="css=...") or browser_type(ref="css=...", text=...). Example: browser_find("verification code") -> the OTP input + its css ref.

Snapshot a specific child frame directly. Use when browser_snapshot returns an iframe node with empty/collapsed children — snapshotting the frame is reliable (works for same-origin AND cross-origin frames).

    frame_ref: a frame id ('f1'), an element ref inside the frame ('f1e36'), or the
    <iframe> element's own ref ('e81'). Returns the frame's ARIA tree with refs
    rewritten to 'fNeM' form so they're directly usable with click/type/etc.

Take a PNG screenshot. By default captures the visible viewport; full_page=True captures the entire scrollable page; ref captures a single element.

    output_path: if given, the PNG is WRITTEN TO THAT FILE and the absolute path is returned
    as text (instead of returning the image bytes). Use this to hand a screenshot to an
    out-of-band vision/OCR tool without routing the (large) image bytes through the caller —
    e.g. a text-only LLM driver that delegates 'seeing' to a separate vision model.

Resize the page viewport (e.g. 1920x1080). Affects layout and screenshot size.

Return console messages collected on the current page (type + text).

Wait for a file download to complete and return its saved path.

    Call this before (or immediately after) clicking a download button.
    The first download event is captured, saved to save_dir, and the
    absolute file path is returned. timeout_ms: max wait (default 30s).

Click an element by its snapshot ref (e.g. 'e12' or 'f1e36' for iframe elements). Returns a fresh snapshot.

Type text into a field by ref (top-frame or iframe ref like 'f1e20'). submit=True presses Enter after. Returns a snapshot.

    Pass the string as `text`. `value` is accepted as an alias for `text` (a common slip,
    since browser_fill_form fields use `value`) so the call doesn't hard-error.

Type text into the currently focused element — no ref needed.

    Works on contenteditable rich-text editors (TipTap, Quill, ProseMirror)
    where browser_type / fill() is a no-op. Also the escape hatch when a
    coordinate click focused an iframe field and you need to type into it.
    Pattern: browser_mouse_click(x, y) to focus → browser_keyboard_type(text).
    delay: ms between keystrokes (simulates human typing speed).
    Returns a snapshot.

Fill multiple fields at once. Each field: {ref, value, submit?, clear?}.

Hover over an element by ref. Returns a snapshot.

Select option(s) in a NATIVE by ref (match by value OR visible label). Self- verifies and, on a no-match, returns the available option labels. For a CUSTOM / searchable dropdown (styled div, role=combobox/listbox — most country-code pickers) this will not work — use browser_select_combobox instead. Returns the committed option + a snapshot.

Pick value from a CUSTOM / searchable dropdown or combobox (country & country-code pickers, styled listboxes) where browser_select_option times out. Opens the trigger ref, types value to filter, commits the highlighted option by keyboard (ArrowDown+Enter), then VERIFIES the committed value and falls back to clicking the option by visible text. Filter by the COUNTRY NAME (e.g. 'Germany'), not a dial code ('49') which matches the wrong row. Returns {committed, actual} + a snapshot — if committed=false the selection did NOT take.

Set value on a FRAMEWORK-CONTROLLED input (React/Vue) via the native value setter + input/change events. Use this when browser_type / fill silently leaves the field EMPTY (controlled components re-derive value from state and ignore plain typing — e.g. some OTP and masked phone inputs). Returns the resulting value + a snapshot.

Enter an OTP/verification code into the field at ref, handling MULTI-BOX widgets (one per digit that auto-advances) by distributing the digits across the boxes via the React-tracked setter — instead of typing the whole code into box 1 (which lands the digits in the wrong boxes). Works on a single field too. Returns {boxes, value} (read it back) + a snapshot. After this, still SUBMIT (Enter / a Verify button).

Press a keyboard key (e.g. 'Enter', 'Escape', 'ArrowDown', 'Tab'). Returns a snapshot.

Drag one element onto another (by refs). Returns a snapshot.

Set files on a file by ref (absolute paths). Returns a snapshot.

Accept or dismiss an open JS dialog (alert/confirm/prompt). prompt_text fills a prompt() before accepting. Dialogs stay open until handled.

Wait for a condition then return a fresh snapshot. Pass exactly one condition:

    text        — text to become visible (searched across all frames including iframes).
    text_gone   — text to disappear.
    selector    — CSS/Playwright selector to become visible.
    url         — URL glob/regex to wait for (SPA client-side navigation).
    network_idle — wait until no network requests for 500ms (SPA render complete).
    value_ref + value — wait until the element at value_ref HOLDS `value` (substring). Confirms a
        field/dropdown actually committed (e.g. value_ref=<country picker>, value='Germany').
    time        — wait N seconds unconditionally.
    timeout_ms  — max wait in ms (default 30 000).
    

Evaluate a JS expression or function in the page and return the result.

    frame_ref: run the JS INSIDE a child frame instead of the top document. Accepts
    a frame id ('f1'), an element ref inside the frame ('f1e36'), or an <iframe>
    element ref ('e81'). This works for CROSS-ORIGIN frames too — the code runs in
    the frame's own context (unlike top-frame JS reaching in via contentDocument,
    which the browser blocks). This is the fix for "Permission denied to access
    property document on cross-origin object".
    Examples: 'document.title'  |  '() => window.location.href'
    

Scroll the page by pixels in a direction, or scroll an element into view.

    direction: 'up' | 'down' | 'left' | 'right'. amount: pixels (default 300).
    ref: if given, scrolls that element into view (direction/amount ignored).
    Use this to trigger lazy-loaded content or reveal off-screen elements.
    Returns a snapshot.

Scroll to the very bottom of the page, pausing to let lazy content load.

    Stops when the page height stops growing (infinite scroll exhausted or real
    bottom reached). max_scrolls: safety cap. wait_ms: pause per step.
    Returns a snapshot of the final state.

List network requests seen this session (method, url, status, resource_type). Optionally filter by resource_type (e.g. 'xhr', 'fetch', 'document') or url substring. For full details including headers and body, use browser_network_request.

Get one request's full detail: request + response headers, and response body (auto-captured for XHR/fetch resource types — body may still be populating for very recent requests). Match by list index or url substring (most recent match).

Return all WebSocket connections opened this session and their messages.

    Each entry: {url, closed, messages: [{dir: 'sent'|'received', data: str}]}.
    url_contains: filter to connections whose URL includes this substring.
    Useful for real-time apps (trading dashboards, chat, live data feeds) that
    deliver state over WebSocket rather than HTTP.

Save cookies + localStorage to a JSON file. Reload it later via browser_new_session(storage_state=path). Returns the file path.

Finalize and return the HAR file path for a recording session.

    NOTE: This CLOSES the session — Playwright only flushes the HAR buffer when
    the browser context closes. The session must have been created with record_har=True.

    output_path: copy the finished HAR to this path (e.g. 'results/run1.har').
        If omitted, the HAR stays at its auto-generated path under data/har/.

    Non-destructive checkpoint pattern (to keep browsing after capturing traffic):
      1. browser_storage_state(path='data/checkpoint.json')   # save auth/cookies
      2. browser_har_export()                                  # closes session, flushes HAR
      3. browser_new_session(storage_state='data/checkpoint.json')  # resume
    

Start a fresh browser identity in a new session: a novel fingerprint (randomized OS + screen) with isolated storage, optionally paired with a proxy. Proxyless by default; pass proxy_url ('http://user:pass@host:port') or proxy_server[+username/password] to pair an IP. persistent=True mints a reusable profile dir. Returns the new session info.

Pin a proxy as the default for subsequent sessions/identities. (Proxies are bound at launch, so existing sessions are unaffected.)

Solve a captcha on the current page and inject the token (no extension).

    kind: 'turnstile' | 'recaptcha_v2' | 'recaptcha_v3' | 'hcaptcha' | 'funcaptcha'.
    website_key is auto-detected from the DOM if omitted (for FunCaptcha that's the
    public key). provider defaults to the configured one (needs that provider's API
    key in the environment). Returns the solved token.

    recaptcha_v3: pass page_action (must match the site's grecaptcha.execute action)
      and optionally min_score (0.1–0.9); the token is injected and grecaptcha.execute
      is overridden to return it.
    funcaptcha (Arkose): funcaptcha_subdomain (the Arkose 'surl') and funcaptcha_data
      (the dynamic 'blob' JSON string) are passed through for sites that require them.
    

Generate a TOTP (time-based one-time password) from a base32 shared secret.

    No browser or session needed — this is a pure computation tool.
    Use it when a site uses an authenticator app (Google Authenticator, Authy, etc.)
    as the second factor. The secret is the base32 string shown during 2FA setup
    (usually labeled 'secret key' or encoded in the QR code's otpauth:// URI).

    digits: code length (default 6). interval: time step in seconds (default 30).
    Returns the current 6-digit (or N-digit) TOTP code as a string.
    

List cookies in the context (optionally filtered to a url).

Get a single cookie by name (or null if absent).

Set a cookie. Provide either url, or domain+path.

Delete the cookie with the given name.

Remove all cookies in the context.

List all localStorage key/value pairs for the current origin.

Get a localStorage value by key (null if absent).

Set a localStorage key to a value.

Remove a localStorage key.

Clear all localStorage for the current origin.

List all sessionStorage key/value pairs for the current origin.

Get a sessionStorage value by key (null if absent).

Set a sessionStorage key to a value.

Remove a sessionStorage key.

Clear all sessionStorage for the current origin.

Move the mouse to absolute page coordinates (x, y).

Click at absolute coordinates (x, y). button: left|right|middle; clicks for multi-click.

Press a mouse button down (at the current position).

Release a mouse button (at the current position).

Scroll the mouse wheel by (delta_x, delta_y) pixels.

Drag from (x1, y1) to (x2, y2) with the left button held.

Abort requests matching glob patterns (e.g. '/*.png', '/ads/**'). Useful to save proxy bandwidth or strip trackers/images.

Remove all URL routes added via browser_block_urls or browser_mock_url.

Toggle the context's network offline/online (to test offline behavior).

Fulfill requests matching a glob pattern with a canned response (response mocking / fault injection). Cleared by browser_unblock_urls.

Assert an element (by ref) is visible. Returns {ok, ...}.

Assert an element (by ref) is hidden/absent. Returns {ok, ...}.

Assert some visible text appears on the page. Returns {ok, ...}.

Assert an input/element (by ref) has the expected value. Returns {ok, ...}.

Draw a magenta outline around an element (by ref) — handy before a screenshot.

Remove all highlight outlines added via browser_highlight.

Return a stable CSS selector for an element (by ref) for use in code/tests.

Start a Playwright trace (screenshots + DOM snapshots) for later inspection.

Stop tracing and write a trace.zip (open with playwright show-trace). Returns the path.

Override the geolocation the page reads (note: geoip already aligns geo to the IP).

Set extra HTTP headers sent with every request in this session.

Pre-grant browser permissions so the native prompt never blocks the flow.

    permissions: list of permission names, e.g. ['geolocation'], ['notifications'],
        ['camera'], ['microphone'], ['clipboard-read'], ['clipboard-write'].
    origin: restrict the grant to a specific origin (e.g. 'https://example.com');
        omit to apply session-wide.

    Call this before navigating to a page that requests permissions, or immediately
    when a permission prompt appears (it will dismiss the prompt automatically).

Click an element by its [ref=...] using a TRUSTED, cursorless CDP input event.

    Preferred over browser_mouse_click: no visible cursor, no pixel guessing (the click point
    is computed from the element's own box), and the event is isTrusted=true — so it passes
    bot-detection that flags DOM .click()/dispatchEvent (isTrusted=false). Chromium only.
    Returns a fresh ARIA snapshot.
    

Send a raw Chrome DevTools Protocol command and return its result.

Escape hatch for any CDP capability not wrapped elsewhere — e.g. method='Network.getResponseBody' {requestId}, 'Network.getRequestPostData' {requestId}, 'Emulation.setGeolocationOverride', 'Emulation.setDeviceMetricsOverride', 'Network.emulateNetworkConditions', 'Performance.getMetrics'. Chromium only.

Save the full page as a single-file MHTML archive (iframes + shadow DOM + external resources + inline styles) via CDP Page.captureSnapshot — captures the exact page state for debugging/forensics. Chromium only. Returns the saved file path.

Save the current page as a PDF file. Chromium only. Returns the saved file path.