Python 3 Examples

The following examples demonstrate how to handle session creation, command execution, and extraction seamlessly using the library. We've broken these down into modular pieces you can chain together.

1. Minimal Execution & Scraping

This example shows how to open a URL and retrieve its HTML or take a screenshot.

python
import json
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

# Use a context manager to ensure the session is properly stopped
with client.create_session(
    enable_proxy=True,
    proxy_tier="basic",
    proxy_policy="extended",
    country="US"
) as session:

    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    # Execute a batch of manual commands
    result = session.execute([
        commands.open_url(url="https://news.ycombinator.com/"),
        commands.get_html()
    ])
    
    if result.get("status") == "done":
        for cmd in result.get("response", {}).get("commands", []):
            cmd_name = cmd.get("command")
            if cmd.get("offloaded_data_url"):
                print(f"\n[{cmd_name}] Data offloaded to: {cmd['offloaded_data_url']}")
            else:
                print(f"\n[{cmd_name}] Data:\n{json.dumps(cmd.get('data'), indent=2)}")
                
print(f"Session video: {session.video_url}")

print(f"\n--- Session Usage Stats ---")
if session.billing:
    print(f"Total billed: ${session.billing.get('total_billed', 0):.4f}")
if session.proxy_usage:
    print(f"Proxy traffic: {session.proxy_usage.get('total_traffic_mb', 0)} MB")

2. Parsing Text and URLs

Extracting clean text and URLs directly from the rendered page layout.

python
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

with client.create_session() as session:
    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    result = session.execute([
        commands.open_url(url="https://news.ycombinator.com/"),
        commands.parse_text(),
        commands.parse_urls()
    ])
    
    # You can access the returned data for each command in the response array
    if result.get("status") == "done":
        # parse_text returns a raw string natively
        print(result["response"]["commands"][1]["data"])
        # parse_urls returns a dictionary containing 'links' and 'images' arrays
        print(result["response"]["commands"][2]["data"])

print(f"Session video: {session.video_url}")

print(f"\n--- Session Usage Stats ---")
if session.billing:
    print(f"Total billed: ${session.billing.get('total_billed', 0):.4f}")

3. Managing Cookies

You can inject authentication cookies to bypass login screens, or dump cookies after a successful login flow to save the session for later.

python
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

with client.create_session() as session:
    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    result = session.execute([
        commands.inject_cookies(cookies=[{
            "name": "session_id", 
            "value": "12345", 
            "domain": ".ycombinator.com",
            "path": "/",
            "secure": True,
            "httpOnly": True,
            "sameSite": "Lax"
        }]),
        commands.open_url(url="https://news.ycombinator.com/"),
        commands.dump_cookies()
    ])
        
print(f"Session video: {session.video_url}")

print(f"\n--- Session Usage Stats ---")
if session.billing:
    print(f"Total billed: ${session.billing.get('total_billed', 0):.4f}")

4. Interacting via HTML Locators

If you know the DOM structure of the target website, you can use standard CSS selectors to interact with inputs and buttons directly.

python
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

with client.create_session() as session:
    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    result = session.execute([
        commands.open_url(url="https://example.com/login"),
        commands.type(locator={"strategy": "css", "value": "input[name='username']"}, text="my_user"),
        commands.type(locator={"strategy": "css", "value": "input[name='password']"}, text="my_pass"),
        commands.click(locator={"strategy": "css", "value": "button[type='submit']"})
    ])

print(f"Session video: {session.video_url}")

print(f"\n--- Session Usage Stats ---")
if session.billing:
    print(f"Total billed: ${session.billing.get('total_billed', 0):.4f}")

5. Locating Elements & Coordinate Interaction

Websites often use shadow DOMs, canvas, or complex event listeners that break standard HTML selectors. A more robust approach is to retrieve the visual coordinates of an element and simulate human mouse movements.

python
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

with client.create_session() as session:
    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    # First, locate the element's exact coordinates on the rendered page
    locate_result = session.execute([
        commands.open_url(url="https://example.com"),
        commands.locate(strategy="css", value="button#checkout")
    ])
    
    if locate_result.get("status") == "done":
        coords = locate_result["response"]["commands"][1]["data"]
        
        # Then, use those coordinates to perform a human-like click
        if coords and "bounding_box" in coords:
            bbox = coords["bounding_box"]
            center_x = bbox.get("x", 0) + (bbox.get("width", 0) / 2)
            center_y = bbox.get("y", 0) + (bbox.get("height", 0) / 2)
            
            session.execute([
                # Scroll the element into the viewport if needed
                commands.scroll_to_viewport(viewport_idx=coords.get("viewport", 0)),
                commands.click_at(
                    x=center_x, 
                    y=center_y
                )
            ])
            
print(f"Session video: {session.video_url}")

print(f"\n--- Session Usage Stats ---")
if session.billing:
    print(f"Total billed: ${session.billing.get('total_billed', 0):.4f}")

6. Keyboard Controls

Simulate real keystrokes, useful for complex dynamic inputs, search bars, and games.

python
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

with client.create_session(
    enable_proxy=True,
    proxy_tier="basic",
    proxy_policy="extended",
    country="US"
) as session:
    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    result = session.execute([
        commands.open_url(url="https://duckduckgo.com"),
        # Type the query
        commands.type(locator={"strategy": "css", "value": "input[name='q']"}, text="What is the weather?"),
        # Hit Enter
        commands.press(keys=["enter"])
    ])

print(f"Session video: {session.video_url}")

print(f"\n--- Session Usage Stats ---")
if session.billing:
    print(f"Total billed: ${session.billing.get('total_billed', 0):.4f}")

7. Autopilot act + extract (Actions & Data Extraction)

Chain act and extract commands to navigate complex flows before extracting data.

python
import json
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

with client.create_session(
    enable_proxy=True,
    proxy_tier="basic",
    proxy_policy="extended",
    country="US"
) as session:
  
    session_id = session.session_id
    
    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    # Run open_url and Autopilot commands (act + extract)
    print("\nExecuting commands")
    batch_result = session.execute([
        commands.open_url(url="https://news.ycombinator.com"),
        commands.act(
            instruction="type 'llm' in the search box",
            max_steps=2,
            model_size='medium'
        ),
        commands.press(keys='enter'),
        commands.extract(
            data_instruction="Extract the top 5 news titles and their links.",
            json_schema=[{
                "title": "<title of the publication>",
                "url": "<direct URL to the publication>",
                "summary": "<summary of the publication, less than 10 words>",
                "company_mentioned": "<company name mentioned in the publication, set a primary company if multiple have been mentioned>",
            }],
            model_size="small"
        )
    ])
    
    print(f"Batch execution status: {batch_result['status']}")
    
    # Check for the extracted data in the response
    if batch_result["status"] == "done":
        print("\nCommand Outputs:")
        commands_executed = batch_result.get("response", {}).get("commands", [])
        for i, cmd in enumerate(commands_executed):
            cmd_name = cmd.get("command", "unknown")
            data = cmd.get("data", {})
            
            if cmd_name == "extract":
                output = data.get("extracted_json")
            elif cmd_name == "act":
                output = data.get("action_steps")
            else:
                output = data
                
            print(f"\n--- [{i}] {cmd_name.upper()} ---")
            print(json.dumps(output, indent=2))

if session_id:
    print("\n--- Final Session Stats ---")
    final_stats = client.get_session(session_id).metadata
    print(json.dumps(final_stats, indent=2))

8. Autopilot extract (Data Extraction & Pagination)

If you already have a target URL, you can extract structured data directly, including automatically clicking "Next" to traverse multiple pages.

python
import json
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

with client.create_session() as session:
    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    result = session.execute([
        commands.open_url(url="https://news.ycombinator.com/"),
        commands.extract(
            data_instruction="Extract a list of top publications on this page",
            json_schema=[{
                "title": "<post title>",
                "link": "<post URL>",
                "points": "<number of points>"
            }],
            model_size="medium",
            paginate=True,
            pages_to_paginate=2
        )
    ])
    
    if result.get("status") == "done":
        for cmd in result.get("response", {}).get("commands", []):
            print(f"\n[{cmd.get('command')}] Data:\n{json.dumps(cmd.get('data'), indent=2)}")

print(f"Session video: {session.video_url}")

print(f"\n--- Session Usage Stats ---")
if session.billing:
    print(f"Total billed: ${session.billing.get('total_billed', 0):.4f}")
if session.tokens:
    print(f"LLM Tokens: {session.tokens.get('total', 0)}")

9. Autopilot act (Actions + Data research)

Use the act command to let the AI navigate complex pages and perform goals on your behalf. You can also extract data at the end of the action. When extract_data argument is enabled, bro searches for target data (json_schema) based on the instructions provided in instruction and data_instruction.

python
import json
from bro import BroClient, commands

client = BroClient(api_key="your_api_key_here")

with client.create_session(
    enable_proxy=True,
    proxy_tier="basic",
    proxy_policy="extended",
    country="US"
) as session:
    print(f"Session started: {session.session_id}")
    print(f"Session stream: {session.stream_url}")
    
    # Search for laptops and extract info
    result = session.execute([
        commands.open_url(url="https://www.amazon.com/"),
        commands.act(
            instruction="Search for 'gaming laptops' and click on the first organic result. Close any popups or windows that block content, if there're any.",
            max_steps=10,
            model_size="medium",
            extract_data=True,
            data_instruction="Extract specifications of the laptop",
            json_schema={
                "title": "<product title>",
                "price": "<price>",
                "cpu": "<processor type>",
                "gpu": "<graphics card>"
            }
        )
    ])
    
    if result.get("status") == "done":
        for cmd in result.get("response", {}).get("commands", []):
            print(f"\n[{cmd.get('command')}] Data:\n{json.dumps(cmd.get('data'), indent=2)}")

print(f"Session video: {session.video_url}")

print(f"\n--- Session Usage Stats ---")
if session.billing:
    print(f"Total billed: ${session.billing.get('total_billed', 0):.4f}")
if session.tokens:
    print(f"LLM Tokens: {session.tokens.get('total', 0)}")