Skip to content
Registry

browser

v0.2.29

A browser on the iii bus - shared Chromium with persistent, restorable tabs and incognito tabs. Navigate, act, read the page console, pick elements. Also parses HTML natively without a browser (browser::* - css/xpath/regex, element search, markdown).

license: Apache-2.0automationbrowsercdpchromiumextractionparsingscrapingweb

Install

bash
iii trigger compose::add worker=browser@0.2.29

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions70

browser::act

Function

Interact with the page: click (left/right/middle, single or double), hover, type, select a native <select> option, press, scroll, or drag (press at the start point, glide to x2/y2, release). Address elements with a ref from browser::elements (`n4`), browser::snapshot (`e3`) or a pick, or raw viewport coordinates. A ref is scrolled into view first, and a click, type or select on a disabled, hidden or covered element is refused instead of landing on whatever is on top. Typing into an input or textarea by ref replaces its value. Returns once the page had a moment to react.

Request
  • actionstringrequired

    `click`, `hover`, `type`, `select`, `press`, `scroll`, or `drag`.

  • buttonstring

    Mouse button for `click`: `left` (default), `right`, or `middle`.

  • click_countinteger· uint32min 0

    Clicks in the gesture: 2 double-clicks (`click` only, default 1).

  • delta_ynumber· double

    Scroll distance in pixels; positive scrolls down (`scroll`).

  • keystring

    Key name for `press`: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown.

  • optionstring

    Option to choose (`select`, native `<select>` only): its value or visible label.

  • refstring

    Element ref from `browser::elements` (`n4`), `browser::snapshot` (`e3`), `browser::dom::read` (`d7`) or `browser::picked` (`p1`). A click, type or select by ref is refused when the element is disabled, hidden or covered. Refs die on navigation; re-read the page after.

  • session_idstringrequired
  • textstring

    Text to insert (`type`). With a ref to an `<input>` or `<textarea>` it replaces the current value; otherwise it is inserted at the caret.

  • xnumber· double

    Viewport x, when acting by coordinates instead of ref.

  • x2number· double

    Drag end x, in viewport pixels (`drag`). The start is `x`/`y` or a `ref`; the end is `x2`/`y2`.

  • ynumber· double

    Viewport y, when acting by coordinates instead of ref.

  • y2number· double

    Drag end y, in viewport pixels (`drag`).

Response
  • detailstringrequired

    What was done, for the transcript.

  • okbooleanrequired

browser::chromium::install

Function

Download Chromium (Chrome for Testing, Stable, about 200 MB) into the worker's cache (~/.cache/iii/browser/chrome) for a machine with no Chrome or Chromium. Returns at once with a job_id; progress arrives on the browser::chromium-install-progress trigger and in browser::chromium::status. A Chrome installed on the system still takes precedence. Does nothing when a Chromium is already found, unless force=true.

Request
  • forceboolean

    Download even when a Chromium is already found (a system one, or the same version already downloaded).

Response
  • job_idstring

    The install job; its progress arrives on the `browser::chromium-install-progress` trigger and in `browser::chromium::status` (`job`). Absent for `already-installed`.

  • pathstring
  • statusone ofrequired
    one of (3)
    Variant 1
    valuestringenum started
    Variant 2
    valuestringenum running
    Variant 3
    valuestringenum already-installed
  • versionstring

browser::chromium::status

Function

Whether this machine has a Chromium the worker can launch: the binary, its version, where it came from (config, $CHROME, a system install, the copy browser::chromium::install downloaded, or a Playwright/Puppeteer cache), every place searched, whether a download is available here, and the latest install job. Read-only; never starts a browser.

Request
Empty object
Response
  • enginestringrequired

    The configured interactive engine (`chromium` or `lightpanda`). Scrapling's browser tiers use Chromium either way.

  • foundbooleanrequired

    A Chromium the worker can launch exists.

  • installobjectrequired

    Whether `browser::chromium::install` can download a Chromium here.

    • approx_download_mbinteger· uint64requiredmin 0

      Roughly how big the download is.

    • dirstringrequired

      Where the download is kept (`III_BROWSER_CACHE_DIR`, else `${XDG_CACHE_HOME:-~/.cache}/iii/browser`, plus `/chrome`).

    • platformstring

      Chrome for Testing platform: `linux64`, `linux-arm64`, `mac-arm64`, `mac-x64`, or `win64`.

    • reasonstring

      Why there is no download here (unsupported platforms).

    • supportedbooleanrequired

      A Chrome for Testing build exists for this platform.

  • jobany of

    This worker's latest install job, running or finished.

    any of (2)
    Variant 1
    • bytes_doneinteger· uint64requiredmin 0

      Bytes downloaded (downloading) or unpacked (extracting) so far.

    • bytes_totalinteger· uint64min 0

      Total for `bytes_done`, when known.

    • errorstring

      What went wrong (failed).

    • hintstring

      How to fix it, when known (failed) — e.g. the system packages a Linux machine is missing.

    • job_idstringrequired
    • pathstring

      The installed binary (done).

    • phaseone ofrequired
      Show 6 nested
      one of (6)
      Variant 1
      valuestringenum resolving
      Variant 2
      valuestringenum downloading
      Variant 3
      valuestringenum extracting
      Variant 4
      valuestringenum verifying
      Variant 5
      valuestringenum done
      Variant 6
      valuestringenum failed
    • timestampinteger· int64required
    • versionstring

      Chrome for Testing version being installed, once known.

    Variant 2
    valuenull
  • pathstring

    The binary sessions launch.

  • sandboxedboolean

    False when sessions launch this Chromium with `--no-sandbox` (a cache copy on a Linux that blocks the user-namespace sandbox).

  • searchedstring[]required

    The places looked, in order.

  • sourceany of

    Where it came from: `configured`, `env`, `system`, `managed` (the download), `playwright`, or `puppeteer`.

    any of (2)
    Variant 1
    one of (6)
    Variant 1
    valuestringenum configured
    Variant 2
    valuestringenum env
    Variant 3
    valuestringenum system
    Variant 4
    valuestringenum managed
    Variant 5
    valuestringenum playwright
    Variant 6
    valuestringenum puppeteer
    Variant 2
    valuenull
  • versionstring

    `<binary> --version`, first line.

browser::clear-browser-data

Function

Clear ALL browser data: closes every tab's page, quits Chromium, and deletes the profile (every site's cookies, logins, storage, cache) and the downloads on disk. Tabs stay and reopen signed out. Incognito tabs are closed.

Request
Empty object
Response
  • closed_pagesinteger· uint64requiredmin 0

    Tabs whose page was closed to release the profile; they reopen on the next call, signed out.

  • okbooleanrequired
  • profile_dirstringrequired

    The profile directory that was deleted.

browser::clear-data

Function

Clear the browsing data of the site the tab is on: its cookies, its storage, and the shared cache — like a browser's per-site 'Clear cookies and site data'. Other sites keep their logins; browser::clear-browser-data wipes everything.

Request
  • cacheboolean

    Clear the HTTP cache (shared by every tab). Default true.

  • cookiesboolean

    Delete the cookies the current page can see (its site's cookies). Default true.

  • session_idstringrequired
  • storageboolean

    Clear localStorage / sessionStorage / IndexedDB for the current origin. Default true.

Response
  • clearedstring[]required

    What was cleared, for the confirmation message.

  • okbooleanrequired

browser::console::read

Function

Read the session's captured console: console.* calls, uncaught exceptions, and browser-level log entries. Filter with pattern/level and page with since_seq instead of dumping everything.

Request
  • levelstring

    Only entries at this level: `log`, `info`, `warning`, `error`, `debug`, `exception`. `error` also matches `exception`.

  • limitinteger· uint64min 0

    Maximum entries returned, newest kept (default 100).

  • patternstring

    Regex applied to entry text. Use it: dumping an unfiltered console wastes the caller's context.

  • session_idstringrequired
  • since_seqinteger· uint64min 0

    Only entries with `seq` greater than this; resume from the cursor returned as `last_seq`.

Response
  • droppedinteger· uint64requiredmin 0

    Entries evicted from the ring buffer since session start.

  • entriesobject[]required
    • levelstringrequired

      `log`, `info`, `warning`, `error`, `debug`, or `exception`.

    • seqinteger· uint64requiredmin 0

      Monotonic per-session cursor; pass back as `since_seq`.

    • sourcestring

      `url:line` of the emitting frame, when known.

    • textstringrequired
    • timestampinteger· int64required
  • last_seqinteger· uint64requiredmin 0

    Cursor for the next `since_seq`.

browser::cookies::clear

Function

Delete the cookies the tab's current page can see (its site's cookies). Other sites keep theirs; browser::clear-browser-data removes everything.

Request
  • session_idstringrequired
Response
  • okbooleanrequired

browser::cookies::list

Function

List the cookies on the session's current page (name, value, domain, path, flags).

Request
  • session_idstringrequired
Response
  • cookiesobject[]required
    • domainstring
    • expiresnumber· double

      Seconds since the Unix epoch; omitted for a session cookie.

    • http_onlyboolean
    • namestringrequired
    • pathstring
    • same_sitestring

      `Strict`, `Lax`, or `None`.

    • secureboolean
    • valuestringrequired

browser::cookies::set

Function

Set cookies on the session, like importing a cookie file. A cookie without a domain is scoped to the current page's URL. same_site is Strict, Lax, or None.

Request
  • cookiesobject[]required

    Cookies to set. A cookie without a domain is scoped to the current page's URL.

    • domainstring
    • expiresnumber· double

      Seconds since the Unix epoch; omitted for a session cookie.

    • http_onlyboolean
    • namestringrequired
    • pathstring
    • same_sitestring

      `Strict`, `Lax`, or `None`.

    • secureboolean
    • valuestringrequired
  • session_idstringrequired
Response
  • countinteger· uintrequiredmin 0

    How many cookies were sent.

  • okbooleanrequired

browser::crawl

Function

Crawl a site from start_urls (same-domain links), extract per page; all items via browser::crawl::items.

Request
  • allowed_domainsstring[]

    only follow links on these hosts

  • concurrencyinteger
  • crawl_idstring

    id for this crawl (default: random). Bind browser::crawl-item with this crawl_id before calling to receive items live; must not match a running crawl

  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • download_delaynumber

    seconds to wait between crawl rounds

  • fetcherstringenum http, stealthy, dynamic
  • formatstringenum markdown, text

    render page body to this format

  • impersonatestring
  • include_htmlboolean
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • max_depthinteger
  • max_pagesinteger
  • same_domainboolean

    follow only same-host links (default true)

  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • start_urlsstring[]
  • stream_namestring

    deprecated, ignored (adds a warning): items are no longer written to a stream; use browser::crawl::items or the browser::crawl-item trigger

  • urlstring

    single start URL (alternative to start_urls)

Response
  • crawlobject
    • dropped_eventsinteger

      live events dropped because a slow consumer filled the bounded queue; read those items back

    • idstring

      pass to browser::crawl::items, or as the browser::crawl-item crawl_id filter

    • items_functionstring

      browser::crawl::items: paginated read of every retained item

    • retainedinteger

      items readable with browser::crawl::items (less than stats.crawled when a retention cap was hit)

    • trigger_typestring

      browser::crawl-item: live per-item events

  • itemsobject[]

    a sample (at most 10) of the crawl's items; read all of them with browser::crawl::items

    Empty object
  • statsobject
    • crawledinteger
    • errorsinteger
    • itemsinteger
    • stoppedstring
  • streamobject

    deprecated echo kept for older callers: stream_name and the crawl id; nothing is written to a stream. Use crawl.id

    • group_idstring
    • namestring
  • warningsstring[]

    present when the request used deprecated input such as stream_name

browser::crawl::items

Function

Page through every item a recent browser::crawl retained (by crawl.id, in seq order).

Request
  • afterinteger

    return items with seq greater than this (default 0); pass next_after to continue

  • crawl_idstringrequired

    crawl.id from browser::crawl

  • limitinteger

    items per page, 1-100 (default 20)

Response
  • crawl_idstring
  • itemsobject[]

    retained items in crawl order; seq matches the browser::crawl-item events

    • itemobject
    • seqinteger
  • next_afterinteger

    present when more retained items follow

  • retainedinteger
  • runningboolean

    the crawl is still in progress

  • statsobject

    the crawl's final stats, once it finished

  • truncatedboolean

    a retention cap was hit; items after the retained ones were not kept

browser::css

Function

Query HTML with a CSS selector; first-or-all; `attr` pulls an attribute.

Request
  • adaptiveboolean

    relocate elements after a site change via saved identities

  • adaptive_domainstring

    page URL/domain that keys saved identities

  • attrstring
  • auto_saveboolean

    save matched identities (defaults on when adaptive)

  • firstboolean
  • htmlstringrequired
  • identifierstring

    stable key for the saved element

  • querystringrequired
Response
  • resultstring[]

browser::describe

Function

Describe the first css/xpath match: attrs, generated selectors, class list, DOM context.

Request
  • htmlstringrequired
  • kindstringenum css, xpath
  • querystringrequired
Response
  • elementobject
    • attrsobject
    • childreninteger
    • classesstring[]
    • cssstring
    • full_cssstring
    • full_xpathstring
    • htmlstring
    • parent_tagstring
    • siblingsinteger
    • tagstring
    • textstring
    • xpathstring
  • foundboolean

browser::doctor

Function

Diagnose the browser environment: which Chromium the worker would launch, its version, session capacity, and any degraded capability with how to enable it. Never starts a browser.

Request
Empty object
Response
  • active_sessionsinteger· uint64requiredmin 0

    Tabs with a page open right now.

  • allow_cookie_importbooleanrequired
  • allow_history_accessbooleanrequired
  • allowed_schemesstring[]required
  • attach_enabledbooleanrequired

    Whether attach mode is enabled (allow_attach).

  • browser_runningbooleanrequired

    Whether the shared Chromium process is running.

  • chromium_pathstring

    The engine binary the worker would launch (a Chromium/Chrome, or the `lightpanda` binary). The field name predates the `engine` setting.

  • chromium_sourceany of

    Where the Chromium came from: `configured`, `env`, `system`, `managed` (downloaded by browser::chromium::install), `playwright`, or `puppeteer`. Absent for Lightpanda or when nothing was found.

    any of (2)
    Variant 1
    one of (6)
    Variant 1
    valuestringenum configured
    Variant 2
    valuestringenum env
    Variant 3
    valuestringenum system
    Variant 4
    valuestringenum managed
    Variant 5
    valuestringenum playwright
    Variant 6
    valuestringenum puppeteer
    Variant 2
    valuenull
  • chromium_versionstring

    `<binary> --version`, first line.

  • configured_origin_policiesinteger· uint64requiredmin 0
  • data_dirstringrequired

    Where the profile, downloads and tab list live.

  • default_origin_policy_setbooleanrequired
  • enginestringrequired

    Configured engine: `chromium` or `lightpanda`.

  • headless_defaultbooleanrequired
  • issuesobject[]required
    • enable_howstringrequired
    • whatstringrequired
  • max_sessionsinteger· uint64requiredmin 0

    Live-tab cap (`max_sessions`).

  • okbooleanrequired

    True when sessions can start right now.

  • open_tabsinteger· uint64requiredmin 0

    Every tab, live or asleep.

  • recording_availablebooleanrequired

    Whether ffmpeg is on PATH, which browser::recording requires.

browser::dom::read

Function

Read the DOM as a tree of tags with id/class and refs. Structure-oriented complement to browser::snapshot; read deep subtrees by passing a ref.

Request
  • depthinteger· uint32min 0

    Levels of children to include (default 3).

  • refstring

    Subtree root from an earlier ref (`e3`/`p1`) or dom node. Omit for the document root.

  • session_idstringrequired
Response
  • rootobjectrequired

    One DOM node in the outline. `ref` resolves in `browser::act`, `browser::styles::read`, and `browser::styles::write`.

    • child_countinteger· uint32requiredmin 0

      Total children in the document, which may exceed `children` returned at this depth.

    • childrenunknown[]
    • classesstring
    • idstring
    • refstringrequired
    • tagstringrequired

      Lowercase tag (`div`, `button`) or node name (`#text`).

    • textstring

      Trimmed text content for text nodes.

  • truncatedbooleanrequired

    True when the node cap cut the tree short; read a subtree via `ref`.

browser::download

Function

Read a downloaded file's bytes for saving or attaching to the chat. Base64; guid from browser::downloads::list.

Request
  • guidstringrequired

    The download's CDP guid, from `browser::downloads::list`.

  • session_idstringrequired
Response
  • datastringrequired

    The file, base64.

  • file_namestringrequired
  • okbooleanrequired
  • size_bytesinteger· uint64requiredmin 0

browser::download::remove

Function

Forget a download and delete its file from the session's download dir.

Request
  • guidstringrequired

    The download to forget, and delete from disk.

  • session_idstringrequired
Response
  • okbooleanrequired

browser::downloads::list

Function

List the files this session downloaded (name, url, size, state), newest first. Read one with browser::download.

Request
  • session_idstringrequired
Response
  • downloadsobject[]required

    Newest first.

    • file_namestringrequired
    • guidstringrequired
    • received_bytesinteger· uint64requiredmin 0
    • started_msinteger· int64required
    • statestringrequired

      `in_progress`, `completed`, or `canceled`.

    • total_bytesinteger· uint64requiredmin 0
    • urlstringrequired

browser::dynamic-fetch

Function

Scrape a JS-rendered URL with Playwright/Chromium: waits, XHR capture, CDP.

Request
  • block_adsboolean
  • blocked_domainsstring[]
  • capture_xhrstring
  • cdp_urlstring
  • cookiesobject
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • disable_resourcesboolean
  • dns_over_httpsboolean
  • extra_flagsstring[]
  • extra_headersobject
  • formatstringenum markdown, text

    render page body to this format

  • google_searchboolean
  • headlessboolean
  • include_htmlboolean
  • load_domboolean
  • localestring
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • max_pagesinteger
  • network_idleboolean
  • proxystring
  • real_chromeboolean
  • retriesinteger
  • retry_delaynumber
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • timeoutnumber

    milliseconds (browser fetcher)

  • timezone_idstring
  • urlstring
  • urlsstring[]
  • useragentstring
  • waitnumber

    extra ms to wait after load

  • wait_selectorstring
  • wait_selector_statestringenum attached, detached, visible, hidden
Response
  • captured_xhrobject[]
    Empty object
  • contentstring

    markdown/text render when `format` requested

  • cookiesobject
  • encodingstring
  • errorstring
  • extractedobject
  • formatstring
  • headersobject
  • htmlstring
  • resultsobject[]
    Empty object
  • statusinteger
  • urlstring

browser::elements

Function

The page's visible, enabled controls in the viewport as an indexed table (ref, role, label, current value, checked/expanded state, what browser::act can do with each, and <select> options), plus the visible text, from one read. Cheaper and flatter than browser::snapshot: use it to drive forms and read what an action changed. Refs (`n4`) stay valid while the element stays in the document.

Request
  • session_idstringrequired
Response
  • busyboolean

    The page is still loading: the document, a region marked `aria-busy`, or (in `browser::run`) requests an action started that had not finished when the run stopped waiting.

  • can_scroll_downbooleanrequired
  • can_scroll_upbooleanrequired
  • elementsobject[]required

    Visible, enabled controls inside the viewport, in document order.

    • autocompletestring

      The field's `autocomplete` hint (`username`, `current-password`, …).

    • checkedstring
    • expandedstring
    • input_typestring

      `<input>` type when not `text` (`email`, `password`, `tel`, …).

    • labelstringrequired

      Accessible name (aria-labelledby, aria-label, label, text, title, or placeholder).

    • more_optionsinteger· uint32min 0

      Options beyond the listed 50; `select` still accepts them by label.

    • namestring

      The field's `name` (or `id`).

    • operationsstring[]required

      `click`, `type` and/or `select`.

    • optionsstring[]

      Enabled `<select>` option labels (first 50), for `act` `select`.

    • refstringrequired

      `n` ref `browser::act` accepts; valid while the element stays in this document.

    • rolestringrequired
    • selectedstring
    • valuestring

      Current value of a field or dropdown; a set password reads `(set)`.

  • generationinteger· uint64min 0

    Document generation; navigation advances it and every `n` ref dies.

  • omittedinteger· uint32requiredmin 0

    Controls past the 250-element cap, not listed.

  • textstringrequired

    Visible text in the viewport, up to 6000 characters.

  • titlestringrequired
  • urlstringrequired

browser::evaluate

Function

Evaluate a JavaScript expression in the page and return its completion value. Use for reads the snapshot can't express; prefer browser::act for interactions.

Request
  • expressionstringrequired

    JavaScript expression evaluated in the page. The completion value is returned by value; wrap statements in an IIFE.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on evaluation; clamped to `max_timeout_ms`.

Response
  • errorstring

    Exception text when not `ok`.

  • okbooleanrequired
  • valueunknown

    JSON completion value when `ok`.

browser::execute

Function

Run a multi-step async JavaScript script in the page: top-level await and return work, with log(...), sleep(ms), waitFor(selector), and a state object that persists across execute calls for the session. One call replaces a chain of act/evaluate round-trips; returns { result, logs, state }.

Request
  • codestringrequired

    Async JavaScript body run in the page; `state`, `log(...)`, `sleep(ms)` and `waitFor(selector, { timeout })` are in scope. Return plain JSON.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on the run; clamped to `max_timeout_ms`.

Response
  • errorstring

    Exception text when not `ok`. A "context destroyed" error usually means the script navigated; split the script at the navigation.

  • logsstring[]required

    `log(...)` output collected during the run, in order.

  • okbooleanrequired
  • resultunknown

    The script's return value when `ok`.

  • stateunknownrequired

    Session state after the run; the next execute call sees this as `state`.

browser::extract

Function

Parse HTML with a selector list (css/xpath/regex, text/attr/html, all-or-first).

Request
  • adaptiveboolean

    relocate elements after a site change via saved identities

  • adaptive_domainstring

    page URL/domain that keys saved identities

  • auto_saveboolean

    save matched identities (defaults on when adaptive)

  • htmlstringrequired
  • selectorsobject[]required
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
Response
  • extractedobject

browser::fetch

Function

Scrape a URL over HTTP with TLS impersonation: get/post/put/delete, extraction, bulk.

Request
  • cookiesobject
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • dataobject
  • follow_redirectsboolean
  • formatstringenum markdown, text

    render page body to this format

  • headersobject
  • http3boolean
  • impersonatestring

    TLS/UA fingerprint, e.g. 'chrome'

  • include_htmlboolean
  • jsonobject
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • max_redirectsinteger
  • methodstringenum get, post, put, delete
  • paramsobject
  • proxiesobject

    per-scheme proxies, e.g. {"https": "http://..."}

  • proxystring
  • proxy_authstring[]

    [user, password]

  • retriesinteger
  • retry_delaynumber
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • stealthy_headersboolean
  • timeoutnumber

    seconds (HTTP fetcher)

  • urlstring
  • urlsstring[]
  • verifyboolean
Response
  • captured_xhrobject[]
    Empty object
  • contentstring

    markdown/text render when `format` requested

  • cookiesobject
  • encodingstring
  • errorstring
  • extractedobject
  • formatstring
  • headersobject
  • htmlstring
  • resultsobject[]
    Empty object
  • statusinteger
  • urlstring

browser::find

Function

Find elements by tag/attribute filters (+ optional text regex); BeautifulSoup-style.

Request
  • attrsobject

    attribute filters, e.g. {"class": "card"}

  • firstboolean
  • htmlstringrequired
  • limitinteger
  • tagstring

    tag name or list of tag names

  • text_regexstring

    keep only elements whose text matches this regex

Response
  • countinteger
  • itemsobject[]
    • attrsobject
    • cssstring
    • htmlstring
    • tagstring
    • textstring
    • xpathstring

browser::find-by-regex

Function

Find elements whose text matches a regex pattern.

Request
  • case_sensitiveboolean
  • clean_matchboolean
  • firstboolean
  • htmlstringrequired
  • limitinteger
  • patternstringrequired
Response
  • countinteger
  • itemsobject[]
    • attrsobject
    • cssstring
    • htmlstring
    • tagstring
    • textstring
    • xpathstring

browser::find-by-text

Function

Find elements with this exact text, or `partial` for a substring.

Request
  • case_sensitiveboolean
  • clean_matchboolean

    ignore surrounding/collapsing whitespace

  • firstboolean
  • htmlstringrequired
  • limitinteger
  • partialboolean

    match elements that contain the text

  • textstringrequired
Response
  • countinteger
  • itemsobject[]
    • attrsobject
    • cssstring
    • htmlstring
    • tagstring
    • textstring
    • xpathstring

browser::find-in-page

Function

Find text in the page like the browser's find bar: highlights every match in the live document, scrolls the current one into view, and steps with next / previous. close clears the highlights. Returns count and the 1-based index.

Request
  • actionstring

    `search` (default: run the query from the top), `next`, `previous`, or `close`.

  • case_sensitiveboolean

    Match case. Default false.

  • querystring

    Text to look for. Empty with `action: close` clears the search.

  • session_idstringrequired
Response
  • countinteger· uint64requiredmin 0

    Number of matches in the visible text of the page.

  • indexinteger· uint64requiredmin 0

    1-based index of the highlighted match; 0 when there is none.

  • okbooleanrequired
  • querystringrequired

    The query the counts refer to.

browser::find-similar

Function

Find elements structurally similar to one example element, plus that element.

Request
  • anchorstringrequired

    CSS selector to one example element

  • htmlstringrequired
  • match_textboolean
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • similarity_thresholdnumber
Response
  • countinteger
  • itemsobject[]
    Empty object

browser::frame

Function

Internal: newest screencast frame, or nothing when since_frame is still current. No capture round-trip: a viewer reads it once for its first paint, then frames arrive on browser::frame-event. Not an agent function.

Request
  • session_idstringrequired
  • since_frameinteger· uint64min 0

    Frame cursor from the previous read; the response omits `frame` while the newest frame still has this seq.

Response
  • activebooleanrequired

    False when no screencast is running (call screencast::start first).

  • framestring

    Base64 JPEG of the newest frame; absent when `since_frame` is still current or no frame has arrived yet.

  • frame_seqinteger· uint64requiredmin 0
  • heightinteger· uint32requiredmin 0

    Page-viewport height the frame maps to.

  • timestampinteger· int64required
  • widthinteger· uint32requiredmin 0

    Page-viewport width the frame maps to (input coordinate space).

browser::handoff

Function

Pause a session for a step only a human can do (CAPTCHA, 2FA, payment): show an in-page continue banner and block until the human clicks it, a browser::handoff::confirm call resolves it, or the timeout elapses. Human acknowledgment is not proof — verify the expected page state after it returns.

Request
  • instructionsstringrequired

    What the human must do before the call continues. Shown in the in-page banner and the handoff-requested event.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Give up after this many ms and return `via: "timeout"` (clamped to `max_timeout_ms`); set generously, a human is slow.

Response
  • confirmedbooleanrequired

    True when a human confirmed; false when the wait timed out.

  • handoff_idstringrequired
  • urlstringrequired

    The page URL when the wait ended, so the caller can verify the step actually landed (human acknowledgment is not proof).

  • viastringrequired

    How the confirmation arrived: `in_page`, `confirm_call`, or `timeout`.

browser::handoff::confirm

Function

Resolve a paused browser::handoff by handoff_id, or the one pending handoff for a session_id. The console calls this when the human confirms outside the page.

Request
  • handoff_idstring

    Confirm a specific handoff by id. Omit to confirm the one pending handoff for `session_id`.

  • session_idstring
Response
  • handoff_idstring
  • okbooleanrequired

    True when a pending handoff matched and was resolved.

browser::history

Function

Go back, go forward, or reload the tab's page. History survives the tab sleeping and the worker restarting. Back/forward at the history edge is a no-op with moved=false.

Request
  • actionstringrequired

    `back`, `forward`, or `reload`.

  • session_idstringrequired
Response
  • movedbooleanrequired

    False when back/forward had no entry to move to.

  • okbooleanrequired
  • urlstringrequired

    URL after the action. `back`/`forward` at the history edge is a no-op with ok=true.

browser::history::list

Function

List the pages this session visited, newest first, for a history panel or address-bar suggestions. Filter with query. browser::history moves back / forward / reloads instead.

Request
  • limitinteger· uintmin 0

    Cap on returned entries. Default 100.

  • querystring

    Only entries whose url or title contains this (case-insensitive).

  • session_idstringrequired
Response
  • visitsobject[]required
    • timestampinteger· int64required
    • titlestringrequired
    • urlstringrequired

browser::inject-guidance

Function

Internal: appends browser::* scraping and HTML parsing guidance to the agent system prompt.

Request
  • generateobject
    • system_promptstring
Response
  • mutationsobjectrequired
    • system_promptstring

browser::navigate

Function

Navigate a tab to a URL and wait for the page to load. Like a browser, a network failure or an empty HTTP error response leaves Chromium's error page in the tab and is reported in `error` rather than failing the call. Element refs from earlier snapshots are invalidated by navigation.

Request
  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on the navigation wait; clamped to `max_timeout_ms`.

  • urlstringrequired

    Absolute URL; scheme must be on the configured allowlist.

Response
  • errorstring

    Chromium's error text when the navigation ended on the browser's own error page: a network failure (`net::ERR_NAME_NOT_RESOLVED`), or an empty HTTP error response (`net::ERR_HTTP_RESPONSE_CODE_FAILURE`, a 4xx/5xx with no body). Like a browser, the tab still shows that page and stays usable.

  • okbooleanrequired

    False when the tab shows Chromium's error page instead of the site; see `error`.

  • timed_outbooleanrequired

    True when the load event did not fire inside the timeout; the page may still be usable; snapshot to check.

  • titlestring
  • urlstringrequired

    URL after redirects.

browser::network::read

Function

Read the session's captured network requests (method, URL, status, failures). failed_only=true is the fast path for 'what broke'.

Request
  • failed_onlyboolean

    Only failed requests (network error or status >= 400).

  • limitinteger· uint64min 0

    Maximum entries returned, newest kept (default 100).

  • patternstring

    Regex applied to the request URL.

  • session_idstringrequired
  • since_seqinteger· uint64min 0

    Only entries with `seq` greater than this.

Response
  • droppedinteger· uint64requiredmin 0

    Entries evicted from the ring buffer since session start.

  • entriesobject[]required
    • errorstring
    • failedbooleanrequired
    • methodstringrequired
    • mime_typestring
    • seqinteger· uint64requiredmin 0

      Monotonic per-session cursor; pass back as `since_seq`.

    • statusinteger· int64
    • timestampinteger· int64required
    • urlstringrequired
  • last_seqinteger· uint64requiredmin 0

    Cursor for the next `since_seq`.

browser::on-config-change

Function

Internal: reload browser settings from the authoritative configuration on change.

Request
Empty object
Response
  • okbooleanrequired

browser::pdf

Function

Print the page to a PDF (the browser's Print -> Save as PDF). Returns it base64 with a file name from the title.

Request
  • landscapeboolean

    Landscape orientation. Default portrait.

  • print_backgroundboolean

    Print background colours and images. Default true (what the page looks like, not what a printer would save ink on).

  • scalenumber· double

    Page scale, 0.1–2. Default 1.

  • session_idstringrequired
Response
  • datastringrequired

    The PDF, base64.

  • file_namestringrequired

    Suggested file name, from the page title.

  • okbooleanrequired
  • size_bytesinteger· uint64requiredmin 0
  • urlstringrequired

browser::pick::hint

Function

Internal: element preview at a viewport point (tag, id, classes, bounds) so the console UI can draw a hover highlight in pick mode. Not an agent function.

Request
  • session_idstringrequired
  • xnumber· doublerequired

    Viewport x of the cursor.

  • ynumber· doublerequired

    Viewport y of the cursor.

Response
  • boundsany of

    Viewport-space box to draw the highlight over.

    any of (2)
    Variant 1
    • heightnumber· doublerequired
    • widthnumber· doublerequired
    • xnumber· doublerequired
    • ynumber· doublerequired
    Variant 2
    valuenull
  • classesstring
  • hitbooleanrequired

    False when no element sits at the point.

  • idstring
  • tagstring

    Lowercase tag name.

browser::pick::resolve

Function

Internal: resolve the element at a clicked viewport point and emit browser::picked. The console calls this on a pick-mode click. Not an agent function.

Request
  • session_idstringrequired
  • xnumber· doublerequired

    Viewport x of the click.

  • ynumber· doublerequired

    Viewport y of the click.

Response
  • okbooleanrequired

browser::pick::start

Function

Internal: enter pick mode so the human can select an element in the console UI. Not an agent function.

Request
  • session_idstringrequired
Response
  • okbooleanrequired

browser::pick::stop

Function

Internal: leave DevTools inspect mode without picking. Idempotent. Not an agent function.

Request
  • session_idstringrequired

    Cancelling pick mode on an unknown session succeeds.

Response
  • okbooleanrequired

browser::recording::start

Function

Record a session's live viewport to a video file (webm or mp4). Turns the screencast on if needed and pipes it through ffmpeg, which must be on PATH; browser::doctor reports whether it is available.

Request
  • formatstring

    `webm` (VP9) or `mp4` (H.264). Defaults to webm.

  • pathstringrequired

    Output file path. The extension should match `format`.

  • session_idstringrequired
Response
  • formatstringrequired
  • okbooleanrequired
  • pathstringrequired

browser::recording::stop

Function

Stop a session's recording, finalize the file, and return its path, duration, and frame count. Idempotent: stopping when nothing is recording returns ok=false.

Request
  • session_idstringrequired
Response
  • duration_msinteger· int64required

    Wall-clock duration captured, milliseconds.

  • framesinteger· uint64requiredmin 0

    Frames written to the encoder.

  • okbooleanrequired

    False when no recording was running.

  • pathstring

browser::regex

Function

Run a regex over the visible text of provided HTML; `first` returns the first match, else all.

Request
  • firstboolean
  • htmlstringrequired
  • patternstringrequired
Response
  • resultstring[]

browser::resize

Function

Set the session's live viewport size (CSS pixels). The console calls this as its browser pane resizes so the streamed frame fills the pane with no letterboxing and clicks map 1:1; the device toolbar calls it with a preset. Clamped 200..4000.

Request
  • device_scale_factornumber· double

    Device pixel ratio. Default 1.

  • fitboolean

    Mark this resize as a pane auto-fit; a fit is refused (current size returned) while more than one viewer watches the session.

  • heightinteger· uint32requiredmin 0

    Viewport height in CSS pixels (clamped 200..4000).

  • mobileboolean

    Emulate a mobile device (viewport meta, overlay scrollbars, touch). Default false. The device toolbar sets this for phone presets.

  • session_idstringrequired
  • widthinteger· uint32requiredmin 0

    Viewport width in CSS pixels (clamped 200..4000).

Response
  • heightinteger· uint32requiredmin 0
  • okbooleanrequired
  • widthinteger· uint32requiredmin 0

    The clamped size actually applied.

browser::run

Function

Drive the page toward a goal in one call (fill and submit a form, log in, pick filters, step through a wizard): each step reads the visible controls, asks the judge worker which operation (click, type, select, scroll, wait, done, blocked) and which element, acts, and waits for the requests the action started, until the judge says done or blocked, a field needs text you did not give in `inputs`, nothing changes three times, or the step/time budget runs out. State the goal as the end state to reach ("logged in: the dashboard shows"), not the clicks. Returns the steps taken and the final page table; read it before reporting success, done is the judge's reading, not proof (a login can end on an error). Without a judge worker it returns status judge_unavailable with the page table: drive with browser::elements and browser::act instead.

Request
  • goalstringrequired

    The end state to reach, as the page would show it ("logged in: the dashboard shows", "the bug is saved and listed"), not the clicks to make. Name every value the outcome needs.

  • inputsobject

    Text for fields the goal needs filled: `{"email": "…", "password": "…"}`. A key reaches a field by its `n` ref, by its label (case, accents and punctuation ignored: `email` for "E-mail"), by what the field is (input type, `name`, `autocomplete`: `password` for a password field labelled "Senha"), or as the only key the label contains. Only the keys are shown to the judge.

  • max_stepsinteger· uint32min 0

    Most actions to execute (default 10, at most 60).

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Whole-run budget in ms (default 30000), clamped to `max_timeout_ms`.

Response
  • elapsed_msinteger· uint64requiredmin 0
  • judge_requestsinteger· uint32requiredmin 0
  • needs_textany of
    any of (2)
    Variant 1
    • input_keysstring[]required

      The `inputs` keys the run was given, none of which matched this field.

    • labelstringrequired
    • refstringrequired
    Variant 2
    valuenull
  • pageall ofrequired

    The page as the run left it (`browser::elements` shape).

    all of (1)
    Variant 1
    • busyboolean

      The page is still loading: the document, a region marked `aria-busy`, or (in `browser::run`) requests an action started that had not finished when the run stopped waiting.

    • can_scroll_downbooleanrequired
    • can_scroll_upbooleanrequired
    • elementsobject[]required

      Visible, enabled controls inside the viewport, in document order.

      Show 13 nested
      • autocompletestring

        The field's `autocomplete` hint (`username`, `current-password`, …).

      • checkedstring
      • expandedstring
      • input_typestring

        `<input>` type when not `text` (`email`, `password`, `tel`, …).

      • labelstringrequired

        Accessible name (aria-labelledby, aria-label, label, text, title, or placeholder).

      • more_optionsinteger· uint32min 0

        Options beyond the listed 50; `select` still accepts them by label.

      • namestring

        The field's `name` (or `id`).

      • operationsstring[]required

        `click`, `type` and/or `select`.

      • optionsstring[]

        Enabled `<select>` option labels (first 50), for `act` `select`.

      • refstringrequired

        `n` ref `browser::act` accepts; valid while the element stays in this document.

      • rolestringrequired
      • selectedstring
      • valuestring

        Current value of a field or dropdown; a set password reads `(set)`.

    • generationinteger· uint64min 0

      Document generation; navigation advances it and every `n` ref dies.

    • omittedinteger· uint32requiredmin 0

      Controls past the 250-element cap, not listed.

    • textstringrequired

      Visible text in the viewport, up to 6000 characters.

    • titlestringrequired
    • urlstringrequired
  • reasonstring
  • statusone ofrequired
    one of (6)
    Variant 1
    valuestringenum max_steps, deadline
    Variant 2
    valuestringenum done
    Variant 3
    valuestringenum blocked
    Variant 4
    valuestringenum stalled
    Variant 5
    valuestringenum needs_text
    Variant 6
    valuestringenum judge_unavailable
  • stepsobject[]required

    Executed actions, in order.

    • errorstring

      Why the action was refused or failed; the page was re-read and the judge asked again.

    • judge_msinteger· uint64requiredmin 0
    • labelstring
    • operationstringrequired

      CLICK, TYPE_TEXT, SELECT, SCROLL_UP, SCROLL_DOWN or WAIT.

    • optionstring

      The option chosen (SELECT).

    • page_changedbooleanrequired
    • probabilitynumber· doublerequired

      The judge's probability for the executed choice.

    • refstring

browser::screencast::start

Function

Internal: start the live viewport feed — frames arrive on the browser::frame-event trigger and browser::frame reads the newest. Console-UI plumbing; agents use browser::screenshot. Not an agent function.

Request
  • previewboolean

    A corner thumbnail rather than a pane: streams frames but does not count as a viewer for `browser::resize` fit arbitration.

  • session_idstringrequired
Response
  • okbooleanrequired

browser::screencast::stop

Function

Internal: stop the live frame push. Idempotent. Not an agent function.

Request
  • previewboolean

    Must match the `preview` the start was made with.

  • session_idstringrequired

    Stopping the screencast on an unknown session succeeds.

Response
  • okbooleanrequired

browser::screenshot

Function

Screenshot the session's current page as a JPEG (or a lossless PNG with format=png). Use browser::snapshot for machine-readable structure; screenshot when layout or rendering matters.

Request
  • formatstring

    `jpeg` (default, compressed with the configured quality) or `png` (lossless; what pixel comparisons need).

  • full_pageboolean

    Capture the full scrollable page instead of the viewport.

  • session_idstringrequired
Response
  • contentobject[]required
    • datastring
    • mimestring
    • textstring
    • typestringrequired
  • detailsobjectrequired
    • heightinteger· uint32requiredmin 0
    • session_idstringrequired
    • urlstringrequired
    • widthinteger· uint32requiredmin 0

browser::screenshot-url

Function

Screenshot a URL with a browser fetcher (dynamic or stealthy); returns image content blocks.

Request
  • fetcherstringenum dynamic, stealthy
  • formatstringenum png, jpeg
  • full_pageboolean
  • headlessboolean
  • network_idleboolean
  • proxystring
  • timeoutnumber
  • urlstringrequired
  • wait_selectorstring
Response
  • contentobject[]

    image blocks (one per tile, width<=1024/height<=1536) + a text caption

    • datastring

      base64 image bytes (image blocks)

    • mimestring
    • textstring
    • typestringrequiredenum image, text
  • mimestring
  • urlstring

browser::session-close

Function

Close a scraping session opened with browser::session-open and free its browser/connection. Interactive tabs from browser::sessions::start are not scraping sessions: close those with browser::sessions::stop (passing a tab id here fails). Returns closed=false for an id it does not hold.

Request
  • session_idstringrequired
Response
  • closedboolean

browser::session-fetch

Function

Fetch a URL on an open scraping session (reuses its cookies/state); returns page content, shows nothing. For a page the user should see, use browser::sessions::start + browser::navigate.

Request
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • dataobject
  • formatstringenum markdown, text

    render page body to this format

  • headersobject
  • include_htmlboolean
  • jsonobject
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • methodstringenum get, post, put, delete
  • paramsobject
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • session_idstringrequired
  • urlstringrequired
  • wait_selectorstring
Response
  • captured_xhrobject[]
    Empty object
  • contentstring

    markdown/text render when `format` requested

  • cookiesobject
  • encodingstring
  • errorstring
  • extractedobject
  • formatstring
  • headersobject
  • htmlstring
  • resultsobject[]
    Empty object
  • statusinteger
  • urlstring

browser::session-list

Function

List open scraping sessions: type and idle time.

Request
  • typestringenum http, dynamic, stealthy

    filter by type

Response
  • sessionsobject[]
    • created_atnumber
    • idle_snumber
    • last_usednumber
    • session_idstring
    • typestring

browser::session-open

Function

Open a persistent scraping session (HTTP or headless fetcher) whose session_id reuses cookies and state across fetches. Renders nothing the user can see; to open a page in the visible browser use browser::sessions::start.

Request
  • capture_xhrstring

    regex; capture matching XHRs (browser sessions)

  • headersobject
  • headlessboolean
  • impersonatestring
  • proxiesobject
  • proxystring
  • real_chromeboolean
  • solve_cloudflareboolean
  • timeoutnumber
  • typestringenum http, dynamic, stealthy

    session engine

  • useragentstring
Response
  • session_idstring
  • typestring

browser::sessions::attach

Function

Attach a session to an already-running browser over CDP. Opens a fresh tab the session owns, or adopts a user tab by URL substring and releases it untouched on stop. Reaches the real profile and its logins; needs Chrome started with --remote-debugging-port and allow_attach in config.

Request
  • adopt_url_substringstring

    Adopt the one open tab whose URL contains this substring (released untouched on stop); omit to open a fresh tab the session owns.

  • cdp_urlstringrequired

    CDP endpoint of the running browser: `http://127.0.0.1:9222` (resolved via `/json/version`) or a `ws://` debugger URL.

  • read_onlyboolean

    Inspection-only session; see browser::sessions::start.

  • urlstring

    URL to open in the fresh tab (ignored when adopting). Omit for about:blank.

Response
  • adoptedbooleanrequired

    True when the session adopted an existing user tab (released, not closed, on stop); false when it opened a fresh tab it owns.

  • read_onlybooleanrequired
  • session_idstringrequired
  • urlstringrequired

browser::sessions::list

Function

List every browser tab, live or asleep, with its current URL, title, and activity.

Request
Empty object
Response
  • sessionsobject[]required
    • activebooleanrequired

      True while the tab has its page open. A sleeping tab (false) is listed and usable; the next call on it reopens the page at `url`.

    • console_entriesinteger· uint64requiredmin 0

      Console entries captured since the page opened; 0 while asleep.

    • created_msinteger· int64required
    • headlessbooleanrequired
    • incognitobooleanrequired

      Private tab: nothing persisted, closes instead of sleeping.

    • last_used_msinteger· int64required
    • read_onlybooleanrequired
    • session_idstringrequired
    • titlestring
    • ttl_msinteger· uint64min 0

      Lifetime the tab was opened with, when any.

    • urlstringrequired

browser::sessions::start

Function

Open a browser tab (a session) and return its session_id. Tabs share one browser profile (cookies, logins) and stay open until stopped or until an optional ttl_ms; an unused tab sleeps and wakes on the next call. incognito=true opens a PRIVATE tab: nothing it does is saved, and inactivity closes it for good.

Request
  • headfulboolean

    Force a visible window, overriding the configured `headless` default. Applies when this call launches the browser process; a browser that is already running keeps its mode.

  • incognitoboolean

    INCOGNITO TAB. Opens the tab in a private browser context: it shares no cookies, logins, or storage with the regular tabs, nothing it does is saved to disk (no cookies, no history, no tab record), it does not come back after a restart, and inactivity closes it for good instead of putting it to sleep. Everything lives in memory for as long as the tab does. Use it for logins you do not want kept, or to see a site signed out.

  • previewboolean

    Whether consoles pop a live preview of the new tab (default true). The console's own tab controls pass `false`: the page that opened the tab already shows it, in every console window. Agents leave it.

  • read_onlyboolean

    Inspection-only session for its whole lifetime: act, evaluate, execute and styles::write are rejected; navigation and reads work.

  • ttl_msinteger· uint64min 0

    Optional lifetime in milliseconds: the tab closes on its own this long after it opened, even while in use. Omit for a tab that stays until stopped (what the console does).

  • urlstring

    URL to open immediately. Omit to start on about:blank.

Response
  • errorstring

    Chromium's error text when the requested url did not load and the tab shows the browser's error page instead (a network failure, or an empty HTTP error response such as a 400). Absent when the page came up. The tab is open either way.

  • headlessbooleanrequired
  • incognitobooleanrequired

    True for a private tab; see `incognito` on the request.

  • read_onlybooleanrequired
  • session_idstringrequired

    Pass this to every other browser function.

  • timed_outbooleanrequired

    True when the requested url's load event did not fire inside the default navigation timeout; the tab is open and the page may still be usable; snapshot to check.

  • urlstringrequired

browser::sessions::stop

Function

Close an interactive browser tab (a session from browser::sessions::start or attach) for good; do this when the task is done, since every tab holds a Chromium page. Idempotent: closing an unknown or already-closed tab succeeds with was_running=false. Scraping sessions from browser::session-open close with browser::session-close.

Request
  • session_idstringrequired

    Tab to close. Closing an unknown or already-closed id succeeds.

Response
  • okbooleanrequired
  • was_runningbooleanrequired

    False when the session was already gone.

browser::snapshot

Function

Read the page as an accessibility-tree outline. Lines carry [ref=eN] handles that browser::act accepts; refs stay valid until the next navigation. Prefer this over browser::screenshot; it is cheaper and machine-readable.

Request
  • diffboolean

    Return only what changed since the previous snapshot; a full outline when there is no baseline (first snapshot or after a navigation).

  • session_idstringrequired
Response
  • diffany of

    Present when the caller asked for `diff: true` and a baseline existed. Covers only the emitted nodes of both snapshots; check `truncated` before trusting it as a complete change set.

    any of (2)
    Variant 1
    • addedstring[]required
    • removedstring[]required
    • unchangedinteger· uint64requiredmin 0
    Variant 2
    valuenull
  • generationinteger· uint64requiredmin 0

    Document generation the refs belong to; navigation advances it and kills every ref from earlier generations.

  • titlestring
  • treestringrequired

    Indented outline; lines carry `[ref=eN]` handles for `browser::act`. Empty when `diff` is populated.

  • truncatedbooleanrequired

    True when the tree hit `max_snapshot_nodes` and was cut short. Also the signal that a `diff` may be incomplete: the diff is computed over emitted nodes only, so when either snapshot was truncated a node that was emitted before and capped out now can show up in `removed` even though it still exists (and vice versa for `added`).

  • urlstringrequired

browser::stealthy-fetch

Function

Scrape a bot-protected URL: Camoufox stealth solves Cloudflare, hardens WebRTC/canvas.

Request
  • allow_webglboolean
  • block_adsboolean
  • block_webrtcboolean
  • blocked_domainsstring[]
  • capture_xhrstring
  • cookiesobject
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • disable_resourcesboolean
  • dns_over_httpsboolean
  • extra_flagsstring[]
  • extra_headersobject
  • formatstringenum markdown, text

    render page body to this format

  • google_searchboolean
  • headlessboolean
  • hide_canvasboolean
  • include_htmlboolean
  • load_domboolean
  • localestring
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • max_pagesinteger
  • network_idleboolean
  • proxystring
  • retriesinteger
  • retry_delaynumber
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • solve_cloudflareboolean
  • timeoutnumber

    milliseconds (browser fetcher)

  • timezone_idstring
  • urlstring
  • urlsstring[]
  • useragentstring
  • waitnumber

    extra ms to wait after load

  • wait_selectorstring
  • wait_selector_statestringenum attached, detached, visible, hidden
Response
  • captured_xhrobject[]
    Empty object
  • contentstring

    markdown/text render when `format` requested

  • cookiesobject
  • encodingstring
  • errorstring
  • extractedobject
  • formatstring
  • headersobject
  • htmlstring
  • resultsobject[]
    Empty object
  • statusinteger
  • urlstring

browser::styles::read

Function

Read an element's computed styles (curated design set by default, or named properties) plus its inline style attribute.

Request
  • propertiesstring[]

    Computed property names to return. Omit for a curated design-panel set; pass `["*"]` for every computed property.

  • refstringrequired

    Element ref from `browser::snapshot`, `browser::dom::read`, or a pick.

  • session_idstringrequired
Response
  • inline_stylestring

    The element's inline `style` attribute, when present.

  • propertiesobject[]required
    • namestringrequired
    • valuestringrequired
  • refstringrequired

browser::styles::write

Function

Set one inline CSS property on an element, live in the page. Visual experiment only: the page's source files are untouched, and the edit dies with the next navigation.

Request
  • importantboolean

    Apply with `!important`.

  • propertystringrequired

    CSS property name (`background-color`).

  • refstringrequired

    Element ref to edit.

  • session_idstringrequired
  • valuestringrequired

    CSS value (`#101418`). Empty string removes the inline property.

Response
  • inline_stylestringrequired

    The element's inline `style` attribute after the edit.

  • okbooleanrequired

browser::tabs::list

Function

List the open tabs of a running browser reachable at a CDP endpoint (url, title, and whether a session already adopted each). Read-only; adopt one with browser::sessions::attach.

Request
  • cdp_urlstringrequired

    CDP endpoint of the running browser, as in browser::sessions::attach.

Response
  • tabsobject[]required
    • adoptedbooleanrequired

      True when a session already adopted this tab; it cannot be adopted again until that session stops.

    • titlestring
    • urlstringrequired

browser::to-markdown

Function

Convert HTML to compact Markdown (or text/html); optional CSS scope + main-content clean.

Request
  • css_selectorstring

    convert only the subtree matching this CSS selector

  • formatstringenum markdown, text, html
  • htmlstringrequired
  • main_content_onlyboolean

    strip nav/scripts/hidden nodes first

Response
  • contentstring
  • formatstring

browser::ui-content

Function

Serve the browser worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).

Request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

browser::upload

Function

Upload up to eight base64 files to exactly one input[type=file] selected by CSS. Files are staged privately for the session and removed when it stops.

Request
  • filesobject[]required

    Up to eight files, each at most 25 MB decoded.

    • datastringrequired

      File bytes, base64.

    • namestringrequired

      File name exposed to the page. Path components are rejected.

  • selectorstringrequired

    CSS selector that must match exactly one input[type=file].

  • session_idstringrequired
Response
  • attachedinteger· uintrequiredmin 0
  • file_namesstring[]required
  • okbooleanrequired

browser::xpath

Function

Query HTML with an XPath expression; first-or-all; `attr` pulls an attribute.

Request
  • adaptiveboolean

    relocate elements after a site change via saved identities

  • adaptive_domainstring

    page URL/domain that keys saved identities

  • attrstring
  • auto_saveboolean

    save matched identities (defaults on when adaptive)

  • firstboolean
  • htmlstringrequired
  • identifierstring

    stable key for the saved element

  • querystringrequired
Response
  • resultstring[]

browser::zoom

Function

Zoom the page in, out, to a level (50-200 %) or back to 100 %, the way the browser's zoom menu does. The viewport keeps its size; the page scales inside it. The level belongs to the loaded document and resets on navigation.

Request
  • actionstring

    `in`, `out`, `reset`, `set` (default when `level` is given), or `read` to report the current level without changing it.

  • levelinteger· uint32min 0

    Explicit level in percent (50–200); snapped to the ladder.

  • session_idstringrequired
Response
  • levelinteger· uint32requiredmin 0

    Level in percent now applied to the document.

  • okbooleanrequired

Triggers13

browser::chromium-install-progress

Trigger

A browser::chromium::install job moved: a new phase (resolving, downloading, extracting, verifying, done, failed) or about 1% more bytes. Not a session event: bind without a session_id filter.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::console-event

Trigger

A console/log/exception entry was captured on a session's page.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::crawl-item

Trigger

One page of a browser::crawl was crawled (event: item, in seq order), or the crawl ended (event: done). Filter with crawl_id; bind before calling browser::crawl. Dropped or missed items are read back with browser::crawl::items.

Invocation
  • crawl_idstring

    Only deliver events of this crawl (the `crawl_id` passed to, or returned as `crawl.id` by, `browser::crawl`).

Return
  • crawl_idstringrequired
  • dropped_eventsinteger· uintmin 0

    `done` only: item events dropped because this crawl's queue was full.

  • eventstringrequired

    `item` for one crawled page, `done` once when the crawl ended.

  • itemunknown

    `item` only: the crawl item, page-derived fields cut to 64 KiB.

  • retainedinteger· uintmin 0

    `done` only: items retained for `browser::crawl::items`.

  • seqinteger· uint64requiredmin 0

    1-based position in the crawl. Items carry 1..=n in completion order; `done` carries n + 1. A gap means a dropped event: read the missing positions with `browser::crawl::items`.

  • statsunknown

    `done` only: the crawl's final `stats`.

  • truncatedboolean

    `item` only: true when `item` was cut; the full one is retained.

browser::download-changed

Trigger

A download started, progressed, or finished in a session.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::frame-event

Trigger

Internal: a live screencast frame of a watched tab (console viewport plumbing, high volume).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::handoff-requested

Trigger

A session is paused waiting for a human to complete a step (CAPTCHA, 2FA, payment).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::handoff-resolved

Trigger

A paused handoff finished (confirmed in page, by call, or timed out).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::navigated

Trigger

The session's page committed a navigation.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::network-event

Trigger

A network request was captured (completed or failed) on a session's page.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::picked

Trigger

The human picked an element in inspect mode.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-started

Trigger

A browser tab opened and is ready.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-stopped

Trigger

A browser tab closed for good (stopped, idle, expired, or crashed).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-updated

Trigger

A browser tab woke up (page open again), went to sleep (page closed, tab kept), or its page's title changed.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

Search the registry

Find workers, kits and executables, or jump to a page.