Browser Use Cloud SDK

Cloud-based AI browser agent that autonomously completes web tasks.

When to use this vs. web-fetch:

• Use browser-use-cloud for autonomous multi-step tasks requiring AI reasoning
• Use web-fetch for simple, deterministic browser automation (click this, fill that)

Setup

API key is set in environment: BROWSER_USE_API_KEY

# Install SDK
pip install browser-use-sdk

Quick Examples

Simple Task (Python)

from browser_use_sdk.v3 import AsyncBrowserUse

client = AsyncBrowserUse()

# Run a task and get result
result = await client.run("Find the latest dark pool data for AAPL on unusualwhales.com")
print(result.output)   # str
print(result.status)   # BuAgentSessionStatus
print(result.total_cost_usd)  # Cost tracking

Structured Output

from browser_use_sdk.v3 import AsyncBrowserUse
from pydantic import BaseModel

class DarkPoolData(BaseModel):
    ticker: str
    total_volume: int
    buy_ratio: float
    largest_print: int
    date: str

client = AsyncBrowserUse()
result = await client.run(
    "Get today's dark pool summary for NVDA from unusualwhales.com/stock/NVDA/dark-pool",
    output_schema=DarkPoolData
)
print(result.output)  # DarkPoolData(ticker="NVDA", total_volume=..., ...)

Session Reuse (Multi-Step)

# Create session for multiple tasks
session = await client.sessions.create(proxy_country_code="us")

# First task: Navigate and authenticate
result1 = await client.run(
    "Go to unusualwhales.com and accept cookies",
    session_id=str(session.id),
    keep_alive=True
)

# Second task: Extract data (same session, already set up)
result2 = await client.run(
    "Navigate to the options flow page and get the top 5 largest call sweeps",
    session_id=str(session.id),
    keep_alive=True
)

# Cleanup
await client.sessions.stop(str(session.id))

---

API Reference (v3 Experimental)

Constructor

from browser_use_sdk.v3 import AsyncBrowserUse, BrowserUse

# Async client (recommended)
client = AsyncBrowserUse(
    api_key="...",      # default: BROWSER_USE_API_KEY env var
    base_url="...",     # default: https://api.browser-use.com/api/v3
    timeout=30.0        # HTTP request timeout (not polling timeout)
)

# Sync client (blocking)
client = BrowserUse(api_key="...", base_url="...", timeout=30.0)

# Context manager (sync only)
with BrowserUse() as client:
    result = client.run("Find the top HN post")

run() Parameters

result = await client.run(
    "Your task description",

    # Model selection
    model="bu-mini",           # "bu-mini" (default, faster) or "bu-max" (more capable)

    # Structured output
    output_schema=MyModel,     # Pydantic model for typed output (alias: schema)

    # Session management
    session_id="...",          # Reuse existing session
    keep_alive=False,          # Keep session alive after task (default: False)

    # Cost & proxy
    max_cost_usd=1.0,          # Cost cap in USD
    proxy_country_code="us",   # Residential proxy country (195+ countries)

    # Persistent state
    profile_id="uuid",         # Browser profile (cookies, localStorage persist)
)

SessionResult Fields

After await client.run():

result.output                  # str or Pydantic model
result.id                      # Session UUID
result.status                  # "idle", "running", "stopped", "timed_out", "error"
result.model                   # "bu-mini" or "bu-max"
result.live_url                # Real-time browser monitoring URL

# Cost tracking
result.total_cost_usd          # Total cost (string)
result.llm_cost_usd            # LLM cost
result.proxy_cost_usd          # Proxy cost
result.proxy_used_mb           # Proxy bandwidth used

# Token usage
result.total_input_tokens
result.total_output_tokens

# Timestamps
result.created_at
result.updated_at

Sessions Resource

# Create session (optionally with task)
session = await client.sessions.create(
    proxy_country_code="us",
    profile_id="...",          # Optional: load persistent profile
)

# List sessions
sessions_list = await client.sessions.list(page=1, page_size=20)

# Get session details
details = await client.sessions.get(str(session.id))

# Stop session
await client.sessions.stop(str(session.id), strategy="session")  # Destroy sandbox (default)
await client.sessions.stop(str(session.id), strategy="task")     # Stop task only, keep session

# Delete session
await client.sessions.delete(str(session.id))

File Upload/Download

from browser_use_sdk.v3 import FileUploadItem

# Upload files before running a task
upload_resp = await client.sessions.upload_files(
    str(session.id),
    files=[FileUploadItem(name="data.csv", content_type="text/csv")]
)
# PUT each file to upload_resp.files[i].upload_url

# List files in session workspace
file_list = await client.sessions.files(
    str(session.id),
    include_urls=True,    # Presigned download URLs (60s expiry)
    prefix="outputs/",    # Filter by path
    limit=50,             # Max per page
)

Error Handling

from browser_use_sdk.v3 import BrowserUseError

try:
    result = await client.run("Do something")
except TimeoutError:
    print("SDK polling timed out (5 min default)")
except BrowserUseError as e:
    print(f"API error: {e}")
finally:
    await client.close()

---

Key Concepts

Concept	Description
Task	Text prompt → agent browses autonomously → returns output
Session	Stateful browser sandbox. Auto-created or manual for follow-ups
Profile	Persistent browser state (cookies, localStorage). Survives sessions
Proxies	Set proxy_country_code. 195+ countries. CAPTCHAs auto-handled
Stealth	On by default. Anti-detect, CAPTCHA solving, ad blocking
Models	bu-mini (faster/cheaper) and bu-max (more capable)
Cost control	Set max_cost_usd to cap spending
keep_alive	If True, session stays idle for follow-ups
Live URL	Every session has live_url for real-time monitoring

---

Trading-Specific Examples

Extract Dark Pool Data

from browser_use_sdk.v3 import AsyncBrowserUse
from pydantic import BaseModel
from typing import List

class DarkPoolDay(BaseModel):
    date: str
    volume: int
    buy_ratio: float

class DarkPoolSummary(BaseModel):
    ticker: str
    five_day_avg_buy_ratio: float
    flow_direction: str  # "ACCUMULATION", "DISTRIBUTION", "NEUTRAL"
    daily_data: List[DarkPoolDay]

client = AsyncBrowserUse()

result = await client.run(
    """Go to unusualwhales.com/stock/NVDA/dark-pool and extract:
    1. The 5-day dark pool summary
    2. Daily breakdown with date, volume, and buy ratio
    3. Determine if the flow is ACCUMULATION (>60% buy), DISTRIBUTION (<40% buy), or NEUTRAL""",
    output_schema=DarkPoolSummary,
    model="bu-max"  # Use more capable model for complex extraction
)

print(f"NVDA: {result.output.flow_direction}")
print(f"5-day avg buy ratio: {result.output.five_day_avg_buy_ratio:.1%}")

Extract Options Flow

class OptionFlow(BaseModel):
    ticker: str
    strike: float
    expiry: str
    premium: int
    side: str  # "CALL" or "PUT"
    type: str  # "SWEEP", "BLOCK", etc.

class FlowSummary(BaseModel):
    flows: List[OptionFlow]
    total_call_premium: int
    total_put_premium: int

result = await client.run(
    "Go to unusualwhales.com/flow and get the top 10 largest options trades from today",
    output_schema=FlowSummary
)

Multi-Step Research

# Create persistent session
session = await client.sessions.create(proxy_country_code="us")

# Step 1: Get dark pool data
dp_result = await client.run(
    "Get 5-day dark pool summary for AAPL from unusualwhales.com",
    session_id=str(session.id),
    keep_alive=True
)

# Step 2: Get options chain (same session)
options_result = await client.run(
    "Now navigate to the options page and get ATM call prices for next month expiry",
    session_id=str(session.id),
    keep_alive=True
)

# Step 3: Check news (same session)
news_result = await client.run(
    "Check finviz.com/quote.ashx?t=AAPL for any recent news that might explain the flow",
    session_id=str(session.id)
)

await client.sessions.stop(str(session.id))

Screenshot for Documentation

# The agent can take screenshots as part of tasks
result = await client.run(
    "Go to tradingview.com/symbols/AAPL and take a screenshot of the current price chart",
    keep_alive=True
)

# Download files from session
files = await client.sessions.files(str(result.id), include_urls=True)
for f in files.files:
    print(f.url)  # Download URL

---

v2 API (Legacy)

The v2 API is still available for simpler use cases:

from browser_use_sdk import AsyncBrowserUse

client = AsyncBrowserUse()
result = await client.run("Find the top HN post")

# Stream steps
async for step in client.run("Go to google.com and search"):
    print(f"[{step.number}] {step.next_goal}")

v2-specific parameters

result = await client.run(
    "task",
    llm="...",                    # Model override
    start_url="...",              # Initial page
    max_steps=100,                # Max agent steps
    secrets={"domain": "pass"},   # Credentials
    allowed_domains=["..."],      # Restrict domains
    flash_mode=True,              # Faster but less careful
    vision=True,                  # Screenshot mode
)

---

Best Practices

1. Use structured output — Always define Pydantic models for predictable data extraction
2. Set cost caps — Use max_cost_usd to avoid runaway costs
3. Reuse sessions — For multi-step tasks, create a session and reuse with keep_alive=True
4. Choose the right model — bu-mini for simple tasks, bu-max for complex reasoning
5. Use proxies — Set proxy_country_code for sites with geo-restrictions or anti-bot
6. Handle errors — Wrap in try/except for TimeoutError and BrowserUseError
7. Clean up — Always await client.close() or use context manager

Cost Estimation

Model	Approximate Cost
bu-mini	~$0.01-0.05 per task
bu-max	~$0.05-0.20 per task
+ Proxy	~$0.001 per MB

Monitor costs with result.total_cost_usd after each task.