Overview

Intro

🔮 We've abstracted away the chaos of web so you can focus on building.

bro is a stealth agentic browser built to handle everything from everyday pages to the most complex and well-protected websites. It lets you and your agents reliably navigate the web and extract data at scale without getting blocked.

Instead of juggling low-level CDP commands, managing infrastructure and handling proxies, you control a fully headed, actual rendered Chrome browser through a simple, agents-friendly REST API. Every session runs on an isolated VM instance - you don't share compute resources or IPs.

You only pay for what you use, with transparent, usage-based billing.

Built to run autonomously

• Zero-headache API: 🧘‍♂️ Whether you're navigating, extracting data or parsing DOM, every command has complex underlying logic built-in - it keeps agent in a single tab, handles dynamic page loads, automatically retries failures, handles downloads, manages timeouts and CDP syncs.
• Two powerful modes:
  • Autopilot. 🤖 Let bro take actions on its own to navigate the web and extract structured data on the fly.
  • Manual. 🕹️ Get full control of the browser via agent-friendly commands.
• Stealth features: 🥷 Clean browser fingerprints, human-like interaction, customizable network routing and monitoring.
• Flexible & cost-effective: 📉 Cut costs by customizing proxy and AI configuration based on your specific task.

Core Concepts: Sessions and Commands

• Sessions (1 Session = 1 dedicated VM): When you initialize a session, you are booting up a fully isolated, dedicated browser instance. Sessions are stateful and highly persistent - the browser won't shut down until you explicitly terminate it, or it hits max session time limit.
• Commands & Batching: Commands are the building blocks of your automation (e.g., navigating, retrieving page state, clicking or running AI-powered commands). Sending commands executes a sequential chain of operations in a single HTTP request, drastically reducing network latency and simplifying your code.
• Smart Long-Polling: We've eliminated the need for aggressive polling loops on your end. When you create a session or execute a command, our API holds the connection open until the action completes, the status changes or a maximum polling timeout is reached (typically 15-30s).
• FIFO Execution: All commands sent to a session are processed strictly in a First-In, First-Out (FIFO) queue, ensuring deterministic and reliable execution sequences.

A typical integration flow is:

1. Create a bro session.
2. Wait until it becomes idle.
3. Send commands.
4. Poll the command result until it is done or failed.
5. Stop the session when finished.

Authentication

All API requests must be authenticated using a Bearer token. Include your API key in the Authorization header of your HTTP requests.

http
Authorization: Bearer <YOUR_API_KEY>

If the key is missing or invalid, the API returns 401.

Base URL

text
https://api.getbro.ws

All endpoint paths in this document are relative to that base URL.

Requests and Responses

JSON requests

All request bodies are JSON.

Top-level success flag

Most responses include:

json
{ "success": true }

This means the API request itself was processed successfully. For command execution, always also inspect the command status and, inside batch results, each item in response.commands.

Timestamps

Timestamps are returned as ISO 8601 / RFC 3339 strings, for example:

text
2026-10-01T12:00:00Z

Cloud-hosted screenshots

All screenshots captured during get_screenshot, act and extract commands are automatically uploaded to the cloud. The API will always return public URLs pointing to the hosted screenshots, rather than returning raw image data.

Large payload offloading

Large payloads may be uploaded to object storage instead of being returned inline. In those cases the command result includes offloaded_data_url and data may be null.

Common examples:

• large HTML responses from get_html
• large DOM snapshots from get_snapshot
• large extraction outputs
• large responses from JS code execution

Commands

Commands represent actions you want the browser to perform (e.g., open a URL, click a button, retrieve HTML, execute JS code, interact with a page autonomously, extract data from the page, etc). Commands sent to an active session are pushed into a FIFO queue. You can include any of these commands inside the commands array of your execution request.

Autopilot Commands

Autopilot commands utilize autonomous vision-guided AI agent to interact with the page, understand context and extract structured data without relying on HTML. It is highly resilient to website structural changes. Custom computer vision models combined with LLMs power our autopilot commands.

• act
• extract

Manual Commands

Manual commands give you direct control over the browser allowing you and your agents to plan actions internally. In most cases manual commands let you cut down costs significantly.

Navigation and page state

The following commands allow you to navigate the browser, manage page state, execute JavaScript and handle clipboard operations. These form the foundational building blocks for controlling the browser environment.

• open_url
• get_url
• refresh
• back
• forward
• sleep
• get_pdf
• get_screenshot
• get_html
• get_snapshot
• locate
• inject_cookies
• dump_cookies
• dump_console_logs
• dump_local_storage
• dump_har_logs
• parse_text
• parse_element_text
• parse_urls
• run_js
• copy
• paste

HTML Locator targets

These commands act directly on elements using HTML locators. They penetrate iframes and shadow DOM automatically. For the new commands, you should support two mutually exclusive targeting parameters (element_id or locator), alongside the action-specific parameters. One of them must be provided.

• click
• type
• select

Mouse and viewport controls

The following commands allow you to simulate mouse movements, clicks, scrolling and drag-and-drop operations. These interactions closely emulate human behavior and can be combined to handle complex UI elements.

• hover_at
• click_at
• drag
• scroll
• scroll_to_viewport
• click_and_hold

Keyboard controls

The following commands allow you to simulate keyboard inputs and combination shortcuts. Like mouse controls, they can be batched to execute complex sequences of interactions.

• type_at
• press
• hold_a_key_and_click
• hold_a_key_and_drag
• clear_textbox

Long-polling behavior

bro uses smart long-polling so you do not need aggressive client-side retry loops.

• POST /v1/sessions may hold the connection open up to 15 seconds while waiting for the session to leave queued.
• GET /v1/sessions/{session_id} may hold the connection open up to 15 seconds while the session is still queued or initializing.
• GET /v1/sessions/{session_id}/commands/{command_id} may hold the connection open up to 15-30 seconds while the command is still pending or running.

You should still implement polling on the client side because the connection may return before the final state is reached.

Billing

bro uses a transparent, usage-based billing model. You only pay for what you actually use.

Unified Balance System

Your account has a single unified balance. You can spend this balance on any combination of resources (compute, proxy traffic, AI tokens, etc.) without resource-specific thresholds. The only restriction is the maximum number of concurrent sessions allowed by your current pricing tier. A minimum balance of $1.00 is required to launch a new browser session. If you run out of funds, you can top up your balance at any time.

Resource Types

When operating a bro session, you may consume the following resources:

• Runner: The dedicated compute instance running your browser. You are billed continuously from the moment your session is assigned to a worker until it is terminated or stops due to inactivity.
• Proxy: If you enable proxy, you are billed for the network traffic (in GB) routed through the proxy. Traffic costs depend on the chosen proxy tier (lite, basic or premium). Consumed traffic volume also depends on proxy_policy (html_only, basic, extended or full).
• LLM: Large Language Model tokens are consumed when using AI-powered autopilot commands like act or extract. You are billed separately for prompt (planning and thinking the next steps to execute) and completion (the model’s output commands and extracted data) tokens, depending on the chosen model size (small, medium or large).
• Grounding: Computer vision resources used by the AI agent to understand the page layout and UI elements during act and extract executions.
• OCR: Optical Character Recognition resources used to extract text directly from page screenshots during AI executions.

Tracking Usage

Session endpoint includes detailed real-time billing snapshots:

• total_billed: The total cost of the session so far.
• Cost breakdown by resource type (Runner, Proxy, LLM, Grounding, OCR).
• Detailed proxy usage metrics (bandwidth consumed).
• Detailed AI token usage (prompt vs completion).

Billing sync is periodic, so values are near-real-time rather than guaranteed to update after every single command. When you stop the session, the last billing sync is executed.

Pricing Tiers & Limitations

Your pricing tier dictates both the per-unit cost of resources and the maximum number of concurrent sessions you can run simultaneously:

• Basic Tier: Maximum of 2 concurrent sessions.
• Pro Tier: Maximum of 5 concurrent sessions.
• Ultra Tier: Maximum of 10 concurrent sessions.

All prices are in USD.