Interact with the page: click (left/right/middle, single or double), hover, type, press, scroll, or drag (press at the start point, glide to x2/y2, release). Address elements with a [ref=eN] handle from browser::snapshot (or a pick), or raw viewport coordinates.
actionstring*required
`click`, `hover`, `type`, `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.
refstring
Element ref from `browser::snapshot` (`e3`) or `browser::picked` (`p1`). Refs die on navigation; re-snapshot after.
session_idstring*required
textstring
Text to insert (`type`).
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`).
detailstring*required
What was done, for the transcript.
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.
closed_pagesinteger· uint64*requiredmin 0
Tabs whose page was closed to release the profile; they reopen on the next call, signed out.
profile_dirstring*required
The profile directory that was deleted.
browser::clear-data
functionClear 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.
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_idstring*required
storageboolean
Clear localStorage / sessionStorage / IndexedDB for the current origin. Default true.
clearedstring[]*required
What was cleared, for the confirmation message.
browser::console::read
functionRead 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.
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_idstring*required
since_seqinteger· uint64min 0
Only entries with `seq` greater than this; resume from the cursor returned as `last_seq`.
droppedinteger· uint64*requiredmin 0
Entries evicted from the ring buffer since session start.
entriesobject[]*required
levelstring*required
`log`, `info`, `warning`, `error`, `debug`, or `exception`.
seqinteger· uint64*requiredmin 0
Monotonic per-session cursor; pass back as `since_seq`.
sourcestring
`url:line` of the emitting frame, when known.
timestampinteger· int64*required
last_seqinteger· uint64*requiredmin 0
Cursor for the next `since_seq`.
browser::cookies::clear
functionDelete the cookies the tab's current page can see (its site's cookies). Other sites keep theirs; browser::clear-browser-data removes everything.
session_idstring*required
browser::cookies::list
functionList the cookies on the session's current page (name, value, domain, path, flags).
session_idstring*required
cookiesobject[]*required
expiresnumber· double
Seconds since the Unix epoch; omitted for a session cookie.
same_sitestring
`Strict`, `Lax`, or `None`.
browser::cookies::set
functionSet 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.
cookiesobject[]*required
Cookies to set. A cookie without a domain is scoped to the current page's URL.
expiresnumber· double
Seconds since the Unix epoch; omitted for a session cookie.
same_sitestring
`Strict`, `Lax`, or `None`.
session_idstring*required
countinteger· uint*requiredmin 0
How many cookies were sent.
Crawl a site from start_urls (same-domain links), extract per page, stream items.
allowed_domainsstring[]
only follow links on these hosts
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
main_content_onlyboolean
strip nav/scripts/hidden before rendering
same_domainboolean
follow only same-host links (default true)
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
stream_namestring
stream to emit items on (default browser::crawl)
urlstring
single start URL (alternative to start_urls)
itemsobject[]
a small sample of streamed items
streamobject
read the full item stream via stream::on with this name + group_id
Query HTML with a CSS selector; first-or-all; `attr` pulls an attribute.
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)
identifierstring
stable key for the saved element
browser::describe
functionDescribe the first css/xpath match: attrs, generated selectors, class list, DOM context.
kindstringenum: css, xpath
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.
active_sessionsinteger· uint64*requiredmin 0
Tabs with a page open right now.
allow_cookie_importboolean*required
allow_history_accessboolean*required
allowed_schemesstring[]*required
attach_enabledboolean*required
Whether attach mode is enabled (allow_attach).
browser_runningboolean*required
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_versionstring
`<binary> --version`, first line.
configured_origin_policiesinteger· uint64*requiredmin 0
data_dirstring*required
Where the profile, downloads and tab list live.
default_origin_policy_setboolean*required
enginestring*required
Configured engine: `chromium` or `lightpanda`.
headless_defaultboolean*required
issuesobject[]*required
enable_howstring*required
max_sessionsinteger· uint64*requiredmin 0
Live-tab cap (`max_sessions`).
okboolean*required
True when sessions can start right now.
open_tabsinteger· uint64*requiredmin 0
Every tab, live or asleep.
recording_availableboolean*required
Whether ffmpeg is on PATH, which browser::recording requires.
browser::dom::read
functionRead 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.
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_idstring*required
rootobject*required
One DOM node in the outline. `ref` resolves in `browser::act`, `browser::styles::read`, and `browser::styles::write`.
child_countinteger· uint32*requiredmin 0
Total children in the document, which may exceed `children` returned at this depth.
tagstring*required
Lowercase tag (`div`, `button`) or node name (`#text`).
textstring
Trimmed text content for text nodes.
truncatedboolean*required
True when the node cap cut the tree short; read a subtree via `ref`.
browser::download
functionRead a downloaded file's bytes for saving or attaching to the chat. Base64; guid from browser::downloads::list.
guidstring*required
The download's CDP guid, from `browser::downloads::list`.
session_idstring*required
datastring*required
The file, base64.
size_bytesinteger· uint64*requiredmin 0
Forget a download and delete its file from the session's download dir.
guidstring*required
The download to forget, and delete from disk.
session_idstring*required
browser::downloads::list
functionList the files this session downloaded (name, url, size, state), newest first. Read one with browser::download.
session_idstring*required
downloadsobject[]*required
Newest first.
received_bytesinteger· uint64*requiredmin 0
started_msinteger· int64*required
statestring*required
`in_progress`, `completed`, or `canceled`.
total_bytesinteger· uint64*requiredmin 0
browser::dynamic-fetch
functionScrape a JS-rendered URL with Playwright/Chromium: waits, XHR capture, CDP.
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
formatstringenum: markdown, text
render page body to this format
main_content_onlyboolean
strip nav/scripts/hidden before rendering
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
timeoutnumber
milliseconds (browser fetcher)
waitnumber
extra ms to wait after load
wait_selector_statestringenum: attached, detached, visible, hidden
contentstring
markdown/text render when `format` requested
browser::evaluate
functionEvaluate a JavaScript expression in the page and return its completion value. Use for reads the snapshot can't express; prefer browser::act for interactions.
expressionstring*required
JavaScript expression evaluated in the page. The completion value is returned by value; wrap statements in an IIFE.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on evaluation; clamped to `max_timeout_ms`.
errorstring
Exception text when not `ok`.
valueunknown
JSON completion value when `ok`.
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 }.
codestring*required
Async JavaScript body run in the page; `state`, `log(...)`, `sleep(ms)` and `waitFor(selector, { timeout })` are in scope. Return plain JSON.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on the run; clamped to `max_timeout_ms`.
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.
resultunknown
The script's return value when `ok`.
stateunknown*required
Session state after the run; the next execute call sees this as `state`.
Scrape a URL over HTTP with TLS impersonation: get/post/put/delete, extraction, bulk.
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
formatstringenum: markdown, text
render page body to this format
impersonatestring
TLS/UA fingerprint, e.g. 'chrome'
main_content_onlyboolean
strip nav/scripts/hidden before rendering
methodstringenum: get, post, put, delete
proxiesobject
per-scheme proxies, e.g. {"https": "http://..."}
proxy_authstring[]
[user, password]
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
timeoutnumber
seconds (HTTP fetcher)
contentstring
markdown/text render when `format` requested
Find elements by tag/attribute filters (+ optional text regex); BeautifulSoup-style.
attrsobject
attribute filters, e.g. {"class": "card"}
tagstring
tag name or list of tag names
text_regexstring
keep only elements whose text matches this regex
browser::find-by-regex
functionFind elements whose text matches a regex pattern.
browser::find-by-text
functionFind elements with this exact text, or `partial` for a substring.
clean_matchboolean
ignore surrounding/collapsing whitespace
partialboolean
match elements that contain the text
browser::find-in-page
functionFind 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.
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_idstring*required
countinteger· uint64*requiredmin 0
Number of matches in the visible text of the page.
indexinteger· uint64*requiredmin 0
1-based index of the highlighted match; 0 when there is none.
querystring*required
The query the counts refer to.
browser::find-similar
functionFind elements structurally similar to one example element, plus that element.
anchorstring*required
CSS selector to one example element
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
similarity_thresholdnumber
Internal: newest screencast frame, or nothing when since_frame is still current. No capture round-trip; poll fast. Not an agent function.
session_idstring*required
since_frameinteger· uint64min 0
Frame cursor from the previous read; the response omits `frame` while the newest frame still has this seq.
activeboolean*required
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· uint64*requiredmin 0
heightinteger· uint32*requiredmin 0
Page-viewport height the frame maps to.
timestampinteger· int64*required
widthinteger· uint32*requiredmin 0
Page-viewport width the frame maps to (input coordinate space).
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.
instructionsstring*required
What the human must do before the call continues. Shown in the in-page banner and the handoff-requested event.
session_idstring*required
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.
confirmedboolean*required
True when a human confirmed; false when the wait timed out.
handoff_idstring*required
urlstring*required
The page URL when the wait ended, so the caller can verify the step actually landed (human acknowledgment is not proof).
viastring*required
How the confirmation arrived: `in_page`, `confirm_call`, or `timeout`.
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.
handoff_idstring
Confirm a specific handoff by id. Omit to confirm the one pending handoff for `session_id`.
okboolean*required
True when a pending handoff matched and was resolved.
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.
actionstring*required
`back`, `forward`, or `reload`.
session_idstring*required
movedboolean*required
False when back/forward had no entry to move to.
urlstring*required
URL after the action. `back`/`forward` at the history edge is a no-op with ok=true.
browser::history::list
functionList 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.
limitinteger· uintmin 0
Cap on returned entries. Default 100.
querystring
Only entries whose url or title contains this (case-insensitive).
session_idstring*required
visitsobject[]*required
timestampinteger· int64*required
browser::inject-guidance
functionInternal: appends browser::* scraping and HTML parsing guidance to the agent system prompt.
browser::navigate
functionNavigate 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.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on the navigation wait; clamped to `max_timeout_ms`.
urlstring*required
Absolute URL; scheme must be on the configured allowlist.
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.
okboolean*required
False when the tab shows Chromium's error page instead of the site; see `error`.
timed_outboolean*required
True when the load event did not fire inside the timeout; the page may still be usable; snapshot to check.
urlstring*required
URL after redirects.
browser::network::read
functionRead the session's captured network requests (method, URL, status, failures). failed_only=true is the fast path for 'what broke'.
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_idstring*required
since_seqinteger· uint64min 0
Only entries with `seq` greater than this.
droppedinteger· uint64*requiredmin 0
Entries evicted from the ring buffer since session start.
entriesobject[]*required
seqinteger· uint64*requiredmin 0
Monotonic per-session cursor; pass back as `since_seq`.
timestampinteger· int64*required
last_seqinteger· uint64*requiredmin 0
Cursor for the next `since_seq`.
Internal: reload browser settings from the authoritative configuration on change.
Print the page to a PDF (the browser's Print -> Save as PDF). Returns it base64 with a file name from the title.
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_idstring*required
datastring*required
The PDF, base64.
file_namestring*required
Suggested file name, from the page title.
size_bytesinteger· uint64*requiredmin 0
browser::pick::hint
functionInternal: 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.
session_idstring*required
xnumber· double*required
Viewport x of the cursor.
ynumber· double*required
Viewport y of the cursor.
boundsany of
Viewport-space box to draw the highlight over.
any of (2)
variant 1
heightnumber· double*required
widthnumber· double*required
hitboolean*required
False when no element sits at the point.
tagstring
Lowercase tag name.
browser::pick::resolve
functionInternal: 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.
session_idstring*required
xnumber· double*required
Viewport x of the click.
ynumber· double*required
Viewport y of the click.
browser::pick::start
functionInternal: enter pick mode so the human can select an element in the console UI. Not an agent function.
session_idstring*required
browser::pick::stop
functionInternal: leave DevTools inspect mode without picking. Idempotent. Not an agent function.
session_idstring*required
Cancelling pick mode on an unknown session succeeds.
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.
formatstring
`webm` (VP9) or `mp4` (H.264). Defaults to webm.
pathstring*required
Output file path. The extension should match `format`.
session_idstring*required
browser::recording::stop
functionStop a session's recording, finalize the file, and return its path, duration, and frame count. Idempotent: stopping when nothing is recording returns ok=false.
session_idstring*required
duration_msinteger· int64*required
Wall-clock duration captured, milliseconds.
framesinteger· uint64*requiredmin 0
Frames written to the encoder.
okboolean*required
False when no recording was running.
Run a regex over the visible text of provided HTML; `first` returns the first match, else all.
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.
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· uint32*requiredmin 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_idstring*required
widthinteger· uint32*requiredmin 0
Viewport width in CSS pixels (clamped 200..4000).
heightinteger· uint32*requiredmin 0
widthinteger· uint32*requiredmin 0
The clamped size actually applied.
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.
previewboolean
A corner thumbnail rather than a pane: streams frames but does not count as a viewer for `browser::resize` fit arbitration.
session_idstring*required
Internal: stop the live frame push. Idempotent. Not an agent function.
previewboolean
Must match the `preview` the start was made with.
session_idstring*required
Stopping the screencast on an unknown session succeeds.
browser::screenshot
functionScreenshot 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.
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_idstring*required
detailsobject*required
heightinteger· uint32*requiredmin 0
session_idstring*required
widthinteger· uint32*requiredmin 0
browser::screenshot-url
functionScreenshot a URL with a browser fetcher (dynamic or stealthy); returns image content blocks.
fetcherstringenum: dynamic, stealthy
formatstringenum: png, jpeg
contentobject[]
image blocks (one per tile, width<=1024/height<=1536) + a text caption
datastring
base64 image bytes (image blocks)
typestring*requiredenum: image, text
browser::session-close
functionClose a session and free its browser/connection.
session_idstring*required
browser::session-fetch
functionFetch 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.
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
formatstringenum: markdown, text
render page body to this format
main_content_onlyboolean
strip nav/scripts/hidden before rendering
methodstringenum: get, post, put, delete
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
session_idstring*required
contentstring
markdown/text render when `format` requested
browser::session-list
functionList open scraping sessions: type and idle time.
typestringenum: http, dynamic, stealthy
filter by type
browser::session-open
functionOpen 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.
capture_xhrstring
regex; capture matching XHRs (browser sessions)
typestringenum: http, dynamic, stealthy
session engine
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.
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_urlstring*required
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.
adoptedboolean*required
True when the session adopted an existing user tab (released, not closed, on stop); false when it opened a fresh tab it owns.
read_onlyboolean*required
session_idstring*required
browser::sessions::list
functionList every browser tab, live or asleep, with its current URL, title, and activity.
sessionsobject[]*required
activeboolean*required
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· uint64*requiredmin 0
Console entries captured since the page opened; 0 while asleep.
created_msinteger· int64*required
incognitoboolean*required
Private tab: nothing persisted, closes instead of sleeping.
last_used_msinteger· int64*required
read_onlyboolean*required
session_idstring*required
ttl_msinteger· uint64min 0
Lifetime the tab was opened with, when any.
browser::sessions::start
functionOpen 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.
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.
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.
incognitoboolean*required
True for a private tab; see `incognito` on the request.
read_onlyboolean*required
session_idstring*required
Pass this to every other browser function.
browser::sessions::stop
functionClose a browser tab for good. Idempotent: closing an unknown or already-closed tab succeeds with was_running=false.
session_idstring*required
Tab to close. Closing an unknown or already-closed id succeeds.
was_runningboolean*required
False when the session was already gone.
browser::snapshot
functionRead 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.
diffboolean
Return only what changed since the previous snapshot; a full outline when there is no baseline (first snapshot or after a navigation).
session_idstring*required
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
unchangedinteger· uint64*requiredmin 0
generationinteger· uint64*requiredmin 0
Document generation the refs belong to; navigation advances it and kills every ref from earlier generations.
treestring*required
Indented outline; lines carry `[ref=eN]` handles for `browser::act`. Empty when `diff` is populated.
truncatedboolean*required
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`).
browser::stealthy-fetch
functionScrape a bot-protected URL: Camoufox stealth solves Cloudflare, hardens WebRTC/canvas.
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
formatstringenum: markdown, text
render page body to this format
main_content_onlyboolean
strip nav/scripts/hidden before rendering
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
timeoutnumber
milliseconds (browser fetcher)
waitnumber
extra ms to wait after load
wait_selector_statestringenum: attached, detached, visible, hidden
contentstring
markdown/text render when `format` requested
browser::styles::read
functionRead an element's computed styles (curated design set by default, or named properties) plus its inline style attribute.
propertiesstring[]
Computed property names to return. Omit for a curated design-panel set; pass `["*"]` for every computed property.
refstring*required
Element ref from `browser::snapshot`, `browser::dom::read`, or a pick.
session_idstring*required
inline_stylestring
The element's inline `style` attribute, when present.
propertiesobject[]*required
browser::styles::write
functionSet 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.
importantboolean
Apply with `!important`.
propertystring*required
CSS property name (`background-color`).
refstring*required
Element ref to edit.
session_idstring*required
valuestring*required
CSS value (`#101418`). Empty string removes the inline property.
inline_stylestring*required
The element's inline `style` attribute after the edit.
browser::tabs::list
functionList 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.
cdp_urlstring*required
CDP endpoint of the running browser, as in browser::sessions::attach.
tabsobject[]*required
adoptedboolean*required
True when a session already adopted this tab; it cannot be adopted again until that session stops.
browser::to-markdown
functionConvert HTML to compact Markdown (or text/html); optional CSS scope + main-content clean.
css_selectorstring
convert only the subtree matching this CSS selector
formatstringenum: markdown, text, html
main_content_onlyboolean
strip nav/scripts/hidden nodes first
browser::ui-content
functionServe the browser worker's injected console UI assets (content function for its console:script / console:style triggers).
pathstring*required
The asset path from the trigger config (e.g. `state/page.js`).
contentstring*required
The asset source, verbatim.
content_typestring*required
MIME type the console should serve the asset with.
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.
filesobject[]*required
Up to eight files, each at most 25 MB decoded.
datastring*required
File bytes, base64.
namestring*required
File name exposed to the page. Path components are rejected.
selectorstring*required
CSS selector that must match exactly one input[type=file].
session_idstring*required
attachedinteger· uint*requiredmin 0
file_namesstring[]*required
Query HTML with an XPath expression; first-or-all; `attr` pulls an attribute.
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)
identifierstring
stable key for the saved element
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.
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_idstring*required
levelinteger· uint32*requiredmin 0
Level in percent now applied to the document.
