---
title: "Execute a browser action"
method: POST
path: "/v1/browser/action"
---

# Execute a browser action

`POST /v1/browser/action`

## Request

- Base URL: `https://api.roveapi.com`
- URL: `https://api.roveapi.com/v1/browser/action`
- Auth: HTTP bearer

## Request body

- object
  - `session_id` string, required
  - `action` string, required: One of: navigate, click, fill, select, scroll, wait_for, screenshot, get_text, get_attribute, get_a11y_tree, evaluate, list_pages, switch_page, close_page, wait_for_popup, restore_pages, close_session.
  - `params` object, required
    - `page_id` string: The page to act on, from list_pages or pages_opened. Defaults to the current page. Does not change the current page. Required by switch_page and close_page.
    - `ref` string: An element ref from this page's latest get_a11y_tree, such as e5, or f1e3 inside an iframe.
    - `frame` union: A CSS selector for an iframe, or a list of them for nested iframes. selector, label and ref then resolve inside it.
      - string
      - string[]
    - `timeout_ms` number: navigate, wait_for and wait_for_popup: how long to wait, in milliseconds (wait_for_popup: default 10000, maximum 30000).
    - `after_seq` integer: wait_for_popup: wait for a popup after this page event seq, such as an earlier result's page_events_seq_start. list_pages: report page events after this seq.
    - `decision` 'restore' | 'dismiss': restore_pages: restore reopens the offered pages; dismiss drops the offer.

## Response `200`

Successful response

- object
  - `success` boolean, required
  - `result` object, required
    - `page_id` string: The page the action ran on.
    - `current_page_id` string, nullable
    - `page_events_seq_start` integer: The page event head when the action started.
    - `page_events_seq` integer: The page event head when the action finished.
    - `pages_opened` string[]
    - `pages_closed` string[]
    - `popups_blocked` object[]
      - `page_id` string, required
      - `reason` 'target-policy-refused' | 'page-limit', required
    - `navigations_refused` object[]
      - `page_id` string, nullable, required
      - `frame` 'top' | 'sub' | 'popup', required
    - `pages_replaced` string[]
    - `pages` object[]: list_pages
      - `page_id` string, required
      - `opener_page_id` string, nullable, required
      - `return_to_page_id` string, nullable, required
      - `url` string, required
      - `title` string, required
      - `status` 'open' | 'closed' | 'blocked', required
      - `blocked_reason` 'target-policy-refused' | 'page-limit'
      - `closed_by` 'page' | 'agent' | 'human' | 'crash' | 'session-end' | 'context-lost'
      - `opened_at` string, required
      - `closed_at` string
    - `restore` object, nullable: list_pages in a supervised session
      - `available` true, required
      - `page_count` integer, required
      - `ended_reason` string, required: Why the previous session ended: worker_lost, page_memory_exhausted, browser_unresponsive, runtime_restarted, or unknown.
      - `ended_at` string, required
      - `pages` object[], required
        - `url` string, required
        - `title` string, required
  - `credits_used` number, required
  - `duration_ms` number, required
  - `environment` 'live' | 'test', required

## Other responses

- `401`: RFC 7807 authentication problem
- `402`: RFC 7807 insufficient-credits: the balance does not cover this operation; carries the balance, the packs this key may buy and next_step (buy_credits or ask_owner)
- `404`: RFC 7807 page-not-found: no page with this page_id exists in the session
- `409`: RFC 7807 state/control problem, including page-closed, last-page, and no-restore-offer (restore_pages with no offer)
- `410`: RFC 7807 session-expired problem; a supervised session that ended (including by an API restart) carries reason and controller; reason credit_exhausted adds the out-of-credits extensions (balance, packs_within_limits, purchasing, next_step, links, owner_action_url, retry none)
- `422`: RFC 7807 popup-blocked (reason target-policy-refused or page-limit) or selector-not-found (including a stale ref)
- `503`: RFC 7807 browser-crash: the browser context for this session is no longer available
- `504`: RFC 7807 popup-timeout: wait_for_popup saw no popup in time

---

[API](https://skmtc.dev/roveapi/apis/rove-api.md) · [All operations](https://skmtc.dev/roveapi/apis/rove-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roveapi/apis/rove-api/revisions/0e5d69bde586?raw)