Actions DSL

Actions are the steps your agent takes in a session, supervised or not: it acts with navigate, click and fill, and reads the page with get_a11y_tree or screenshot. While a person holds control of a supervised session, actions are refused until they hand back (see Supervised sessions).

All commands are executed via POST /v1/browser/action with the action name and parameters.

{
  "session_id": "sess_xxxx",
  "action": "navigate",
  "params": { "url": "https://example.com" }
}

navigate

Navigate the browser to a URL.

Result:

{
  "url": "https://example.com",
  "title": "Example Domain",
  "status_code": 200,
  "load_time_ms": 847
}

Credit cost: 1

get_a11y_tree

Extract the accessibility tree from the current page. This is the primary tool for LLM consumption — 77% fewer tokens than a screenshot.

Result:

{
  "tree": "- heading \"Example Domain\" [level=1]\n- link \"More information...\"",
  "node_count": 12,
  "estimated_tokens": 340
}

Credit cost: 1

click

Click an element by CSS selector or accessible label.

Use label when possible — it's more reliable than CSS selectors across page changes.

Credit cost: 1

fill

Type text into an input, textarea, or contenteditable element.

Credit cost: 1

select

Select an option from a <select> element.

Credit cost: 1

scroll

Scroll the page or a specific element.

Credit cost: 1

wait_for

Wait for a condition before proceeding.

Credit cost: 0

screenshot

Capture a screenshot within an active session.

Result:

{
  "url": "https://s3.amazonaws.com/rove-artifacts/scr_xxxx.png?...",
  "expires_at": "2026-04-20T10:00:00Z"
}

Credit cost: 1

get_text

Extract text content from an element.

Result:

{ "text": "$49.99" }

Credit cost: 1

get_attribute

Get an attribute value from an element.

Credit cost: 1

evaluate

Execute JavaScript in the browser context. Power-user escape hatch.

Result:

{
  "value": 23,
  "type": "number"
}

Credit cost: 1

Pages, popups and frames

Every page in a session has an id: p1 for the first, then p2, p3… for each popup or new tab the site opens. Every page action (navigate, click, fill, select, scroll, wait_for, screenshot, get_text, get_attribute, get_a11y_tree, evaluate) takes an optional page_id (default: the current page; it does not change the current page). Element actions also take:

get_a11y_tree shows iframe content, cross-origin included. Every result carries page_id, current_page_id, page_events_seq_start and page_events_seq, plus pages_opened, pages_closed, popups_blocked, navigations_refused and pages_replaced when something changed while it ran. get_text on a form field returns its value (a password field returns "").

In a supervised session a popup becomes the current page, as in a browser; its own window.close() returns the session to the page that opened it. In other sessions the current page stays put until switch_page. Every navigation in a supervised session, in any page or frame, passes the same target policy as navigate: a popup to a refused address is blocked, and a session holds at most 8 open pages.

list_pages

The open pages (then the last 20 closed or blocked ones) with page_id, opener_page_id, url, title and status, the current_page_id, and the page events since the previous list_pages (or after params.after_seq). Does not count as a fresh observation. Credit cost: 0

switch_page

Make another open page current (params.page_id). Credit cost: 0

close_page

Close an open page (params.page_id). If it was current, the session returns to the page that was current when it opened. The last open page cannot be closed (409 last-page). Credit cost: 0

wait_for_popup

Wait for a popup opened by your last navigate, click, fill, select, scroll or evaluate, even one that has already opened, and return its page_id and opener_page_id. A blocked popup answers 422 popup-blocked at once; no popup within timeout_ms (default 10000, max 30000) answers 504 popup-timeout. Pass after_seq (an earlier result's page_events_seq_start) to choose the anchor. Credit cost: 0

{ "session_id": "sess_xxxx", "action": "click", "params": { "selector": "#sign-in" } }
{ "session_id": "sess_xxxx", "action": "wait_for_popup", "params": {} }
{ "session_id": "sess_xxxx", "action": "fill", "params": { "page_id": "p2", "ref": "e5", "value": "alice" } }

close_session

Close a session and trigger artifact upload (if video was recorded).

Returns artifact URLs if record_video was enabled.

Credit cost: 0

Credit Cost Summary