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 Python library. 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 using client.create_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 request, drastically reducing network latency and simplifying your code.
• Built-in Execution Handling: When you execute a command via session.execute(...), the library blocks synchronously and returns only when the action completes, the status changes or a maximum polling timeout is reached.
• 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. Initialize BroClient.
2. Open a session context block with client.create_session() as session:.
3. Send a batch of commands via session.execute([commands.open_url(...), commands.act(...)]).
4. The library natively awaits the result and returns execution data.
5. Once the with block closes, the session safely stops itself automatically.

Installation

Install the package via pip (requires Python 3.8+).

Ensure you're using the latest version of the library.

bash
pip install bro-api-sdk

python
from bro import BroClient, commands

client = BroClient(api_key="<YOUR_API_KEY>")

If the API key is missing or invalid, an authentication exception will be raised.

Responses

Execution Success

When executing a batch of commands, always inspect the command status and each item inside the response commands array.

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 None.

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. You can pass them as a list of CommandPayload models returned from methods inside bro.commands.

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.

• commands.act()
• commands.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

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

HTML Locator targets

These commands act directly on elements using HTML locators. They penetrate iframes and shadow DOM automatically.

• commands.click()
• commands.type()
• commands.select()

Mouse and viewport controls

• commands.hover_at()
• commands.click_at()
• commands.drag()
• commands.scroll()
• commands.scroll_to_viewport()
• commands.click_and_hold()

Keyboard controls

• commands.type_at()
• commands.press()
• commands.hold_a_key_and_click()
• commands.hold_a_key_and_drag()
• commands.clear_textbox()

Execution Behavior

bro-sdk handles HTTP long-polling natively. You do not need to implement client-side retry loops.

• client.create_session() blocks execution while waiting for the session to leave the queued state and become idle.
• session.execute(...) intrinsically holds the connection and waits while the command is pending or running.
• If session.execute(..., await_completion=False) is explicitly invoked, the method will return immediately with the pending state, leaving polling up to the developer (via session.get_command(command_id)).

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 objects in bro-sdk continuously track detailed real-time billing snapshots:

• session.billing: Cost breakdown by resource type (Runner, Proxy, LLM, Grounding, OCR) and total_billed.
• session.proxy_usage: Detailed proxy usage metrics (bandwidth consumed).
• session.tokens: 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.