# Overview

## `bro` 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.

## SDK Sections

- [Exceptions and Error Handling](https://getbro.ws/sdk_exceptions_and_error_handling.md)
- [Integration Recommendations & Best Practices](https://getbro.ws/sdk_integration_recommendations_best_practices.md)
- [Agent Autonomous Sign Up](https://getbro.ws/sdk_agent_autonomous_sign_up.md)
- [User and Billing Management](https://getbro.ws/sdk_user_and_billing_management.md)
- [Session Management](https://getbro.ws/sdk_session_management.md)
- [Command Execution & Querying](https://getbro.ws/sdk_command_execution_querying.md)
- [LLM & Agent Integrations](https://getbro.ws/sdk_llm_agent_integrations.md)
- [Get the tools formatted for OpenAI](https://getbro.ws/sdk_get_the_tools_formatted_for_openai.md)
- [Get the tools formatted for Anthropic](https://getbro.ws/sdk_get_the_tools_formatted_for_anthropic.md)
- [Commands API](https://getbro.ws/sdk_commands_api.md)
- [Python 3 Examples](https://getbro.ws/sdk_python_3_examples.md)
- [Use a context manager to ensure the session is properly stopped](https://getbro.ws/sdk_use_a_context_manager_to_ensure_the_session_is_properly_stopped.md)

## 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 & Initialization
Install `bro-sdk` via pip (or manage via your project's dependency tool). Ensure you're using the latest version of the library.

```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 (`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.*

| Resource | Unit | `Basic`      | `Pro`       | `Ultra`     |
| --- | --- |--------------|-------------|-------------|
| **Compute & Network** | |              |             |             |
| Runner | 1 hour | 0.12         | 0.10        | 0.06        |
| Basic Proxy | 1 GB | 5.00         | 4.00        | 2.50        |
| Premium Proxy | 1 GB | 12.00        | 10.00       | 6.00        |
| **Language Models (Prompt / Completion)** | |              |             |             |
| Small | 1M tokens | 0.375 / 2.25 | 0.30 / 1.80 | 0.27 / 1.62 |
| Medium | 1M tokens | 0.75 / 4.50  | 0.60 / 3.60 | 0.54 / 3.24 |
| Large | 1M tokens | 3.00 / 18.00 | 2.40 / 14.40 | 2.16 / 12.96 |
| **Computer Vision** | |              |             |             |
| Grounding | 1k images | 0.60         | 0.50        | 0.30        |
| OCR | 1k images | 0.80         | 0.65        | 0.40        |
---

You can also view the [Full SDK Documentation](https://getbro.ws/sdk_full.md) which contains all sections combined in a single file.