Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

docs(cloud): replace retired v1 API examples with v4

MagMueller80802eefb9cf
diff --git a/examples/cloud/01_basic_task.py b/examples/cloud/01_basic_task.py
index 54b8ea561..2e88ff668 100644
--- a/examples/cloud/01_basic_task.py
+++ b/examples/cloud/01_basic_task.py
@@ -1,187 +1,56 @@
-"""
-Cloud Example 1: Your First Browser Use Cloud Task
-==================================================
-
-This example demonstrates the most basic Browser Use Cloud functionality:
-- Create a simple automation task
-- Get the task ID
-- Monitor completion
-- Retrieve results
-
-Perfect for first-time cloud users to understand the API basics.
-
-Cost: ~$0.04 (1 task + 3 steps with GPT-4.1 mini)
-"""
+"""Run one Browser Use Cloud API V4 task."""
import os
import time
from typing import Any
import requests
-from requests.exceptions import RequestException
+from dotenv import load_dotenv
-# Configuration
+load_dotenv()
+
+API_URL = os.getenv('BROWSER_USE_API_URL', 'https://api.browser-use.com/api/v4').rstrip('/')
API_KEY = os.getenv('BROWSER_USE_API_KEY')
if not API_KEY:
- raise ValueError(
- 'Please set BROWSER_USE_API_KEY environment variable. You can also create an API key at https://cloud.browser-use.com/new-api-key'
- )
-
-BASE_URL = os.getenv('BROWSER_USE_BASE_URL', 'https://api.browser-use.com/api/v1')
-TIMEOUT = int(os.getenv('BROWSER_USE_TIMEOUT', '30'))
-HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
-
-
-def _request_with_retry(method: str, url: str, **kwargs) -> requests.Response:
- """Make HTTP request with timeout and retry logic."""
- kwargs.setdefault('timeout', TIMEOUT)
-
- for attempt in range(3):
- try:
- response = requests.request(method, url, **kwargs)
- response.raise_for_status()
- return response
- except RequestException as e:
- if attempt == 2: # Last attempt
- raise
- sleep_time = 2**attempt
- print(f'⚠️ Request failed (attempt {attempt + 1}/3), retrying in {sleep_time}s: {e}')
- time.sleep(sleep_time)
-
- # This line should never be reached, but satisfies type checker
- raise RuntimeError('Unexpected error in retry logic')
+ raise RuntimeError('Set BROWSER_USE_API_KEY or add it to .env')
+HEADERS = {'X-Browser-Use-API-Key': API_KEY}
+TERMINAL_STATUSES = {'completed', 'failed', 'cancelled'}
-def create_task(instructions: str) -> str:
- """
- Create a new browser automation task.
- Args:
- instructions: Natural language description of what the agent should do
+def create_run(task: str) -> str:
+ response = requests.post(f'{API_URL}/runs', headers=HEADERS, json={'task': task}, timeout=30)
+ response.raise_for_status()
+ return response.json()['id']
- Returns:
- task_id: Unique identifier for the created task
- """
- print(f'📝 Creating task: {instructions}')
-
- payload = {
- 'task': instructions,
- 'llm_model': 'gpt-4.1-mini', # Cost-effective model
- 'max_agent_steps': 10, # Prevent runaway costs
- 'enable_public_share': True, # Enable shareable execution URLs
- }
-
- response = _request_with_retry('post', f'{BASE_URL}/run-task', headers=HEADERS, json=payload)
-
- task_id = response.json()['id']
- print(f'✅ Task created with ID: {task_id}')
- return task_id
+def wait_for_run(run_id: str, poll_seconds: float = 2) -> dict[str, Any]:
+ while True:
+ response = requests.get(f'{API_URL}/runs/{run_id}/status', headers=HEADERS, timeout=30)
+ response.raise_for_status()
+ status = response.json()['status']
+ print(f'Status: {status}')
-def get_task_status(task_id: str) -> dict[str, Any]:
- """Get the current status of a task."""
- response = _request_with_retry('get', f'{BASE_URL}/task/{task_id}/status', headers=HEADERS)
- return response.json()
+ if status in TERMINAL_STATUSES:
+ break
+ time.sleep(poll_seconds)
-def get_task_details(task_id: str) -> dict[str, Any]:
- """Get full task details including steps and output."""
- response = _request_with_retry('get', f'{BASE_URL}/task/{task_id}', headers=HEADERS)
+ response = requests.get(f'{API_URL}/runs/{run_id}', headers=HEADERS, timeout=30)
+ response.raise_for_status()
return response.json()
-def wait_for_completion(task_id: str, poll_interval: int = 3) -> dict[str, Any]:
- """
- Wait for task completion and show progress.
-
- Args:
- task_id: The task to monitor
- poll_interval: How often to check status (seconds)
+def main() -> None:
+ run_id = create_run('Find the top story on Hacker News and summarize it in one sentence.')
+ print(f'Run: {run_id}')
- Returns:
- Complete task details with output
- """
- print(f'⏳ Monitoring task {task_id}...')
+ run = wait_for_run(run_id)
+ if run['status'] != 'completed':
+ raise RuntimeError(run.get('error') or f'Run {run["status"]}')
- step_count = 0
- start_time = time.time()
-
- while True:
- details = get_task_details(task_id)
- status = details['status']
- current_steps = len(details.get('steps', []))
- elapsed = time.time() - start_time
-
- # Clear line and show current progress
- if current_steps > step_count:
- step_count = current_steps
-
- # Build status message
- if status == 'running':
- if current_steps > 0:
- status_msg = f'🔄 Step {current_steps} | ⏱️ {elapsed:.0f}s | 🤖 Agent working...'
- else:
- status_msg = f'🤖 Agent starting... | ⏱️ {elapsed:.0f}s'
- else:
- status_msg = f'🔄 Step {current_steps} | ⏱️ {elapsed:.0f}s | Status: {status}'
-
- # Clear line and print status
- print(f'\r{status_msg:<80}', end='', flush=True)
-
- # Check if finished
- if status == 'finished':
- print(f'\r✅ Task completed successfully! ({current_steps} steps in {elapsed:.1f}s)' + ' ' * 20)
- return details
- elif status in ['failed', 'stopped']:
- print(f'\r❌ Task {status} after {current_steps} steps' + ' ' * 30)
- return details
-
- time.sleep(poll_interval)
-
-
-def main():
- """Run a basic cloud automation task."""
- print('🚀 Browser Use Cloud - Basic Task Example')
- print('=' * 50)
-
- # Define a simple search task (using DuckDuckGo to avoid captchas)
- task_description = (
- "Go to DuckDuckGo and search for 'browser automation tools'. Tell me the top 3 results with their titles and URLs."
- )
-
- try:
- # Step 1: Create the task
- task_id = create_task(task_description)
-
- # Step 2: Wait for completion
- result = wait_for_completion(task_id)
-
- # Step 3: Display results
- print('\n📊 Results:')
- print('-' * 30)
- print(f'Status: {result["status"]}')
- print(f'Steps taken: {len(result.get("steps", []))}')
-
- if result.get('output'):
- print(f'Output: {result["output"]}')
- else:
- print('No output available')
-
- # Show share URLs for viewing execution
- if result.get('live_url'):
- print(f'\n🔗 Live Preview: {result["live_url"]}')
- if result.get('public_share_url'):
- print(f'🌐 Share URL: {result["public_share_url"]}')
- elif result.get('share_url'):
- print(f'🌐 Share URL: {result["share_url"]}')
-
- if not result.get('live_url') and not result.get('public_share_url') and not result.get('share_url'):
- print("\n💡 Tip: Add 'enable_public_share': True to task payload to get shareable URLs")
-
- except requests.exceptions.RequestException as e:
- print(f'❌ API Error: {e}')
- except Exception as e:
- print(f'❌ Error: {e}')
+ print(f'Result: {run["result"]}')
+ print(f'Cost: ${run["totalCostUsd"]}')
if __name__ == '__main__':
diff --git a/examples/cloud/02_fast_mode_gemini.py b/examples/cloud/02_fast_mode_gemini.py
deleted file mode 100644
index 245da5c20..000000000
--- a/examples/cloud/02_fast_mode_gemini.py
+++ /dev/null
@@ -1,265 +0,0 @@
-"""
-Cloud Example 2: Ultra-Fast Mode with Gemini Flash ⚡
-====================================================
-
-This example demonstrates the fastest and most cost-effective configuration:
-- Gemini 2.5 Flash model ($0.01 per step)
-- No proxy (faster execution, but no captcha solving)
-- No element highlighting (better performance)
-- Optimized viewport size
-- Maximum speed configuration
-
-Perfect for: Quick content generation, humor tasks, fast web scraping
-
-Cost: ~$0.03 (1 task + 2-3 steps with Gemini Flash)
-Speed: 2-3x faster than default configuration
-Fun Factor: 💯 (Creates hilarious tech commentary)
-"""
-
-import argparse
-import os
-import time
-from typing import Any
-
-import requests
-from requests.exceptions import RequestException
-
-# Configuration
-API_KEY = os.getenv('BROWSER_USE_API_KEY')
-if not API_KEY:
- raise ValueError(
- 'Please set BROWSER_USE_API_KEY environment variable. You can also create an API key at https://cloud.browser-use.com/new-api-key'
- )
-
-BASE_URL = os.getenv('BROWSER_USE_BASE_URL', 'https://api.browser-use.com/api/v1')
-TIMEOUT = int(os.getenv('BROWSER_USE_TIMEOUT', '30'))
-HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
-
-
-def _request_with_retry(method: str, url: str, **kwargs) -> requests.Response:
- """Make HTTP request with timeout and retry logic."""
- kwargs.setdefault('timeout', TIMEOUT)
-
- for attempt in range(3):
- try:
- response = requests.request(method, url, **kwargs)
- response.raise_for_status()
- return response
- except RequestException as e:
- if attempt == 2: # Last attempt
- raise
- sleep_time = 2**attempt
- print(f'⚠️ Request failed (attempt {attempt + 1}/3), retrying in {sleep_time}s: {e}')
- time.sleep(sleep_time)
-
- raise RuntimeError('Unexpected error in retry logic')
-
-
-def create_fast_task(instructions: str) -> str:
- """
- Create a browser automation task optimized for speed and cost.
-
- Args:
- instructions: Natural language description of what the agent should do
-
- Returns:
- task_id: Unique identifier for the created task
- """
- print(f'⚡ Creating FAST task: {instructions}')
-
- # Ultra-fast configuration
- payload = {
- 'task': instructions,
- # Model: Fastest and cheapest
- 'llm_model': 'gemini-2.5-flash',
- # Performance optimizations
- 'use_proxy': False, # No proxy = faster execution
- 'highlight_elements': False, # No highlighting = better performance
- 'use_adblock': True, # Block ads for faster loading
- # Viewport optimization (smaller = faster)
- 'browser_viewport_width': 1024,
- 'browser_viewport_height': 768,
- # Cost control
- 'max_agent_steps': 25, # Reasonable limit for fast tasks
- # Enable sharing for viewing execution
- 'enable_public_share': True, # Get shareable URLs
- # Optional: Speed up with domain restrictions
- # "allowed_domains": ["google.com", "*.google.com"]
- }
-
- response = _request_with_retry('post', f'{BASE_URL}/run-task', headers=HEADERS, json=payload)
-
- task_id = response.json()['id']
- print(f'✅ Fast task created with ID: {task_id}')
- print('⚡ Configuration: Gemini Flash + No Proxy + No Highlighting')
- return task_id
-
-
-def monitor_fast_task(task_id: str) -> dict[str, Any]:
- """
- Monitor task with optimized polling for fast execution.
-
- Args:
- task_id: The task to monitor
-
- Returns:
- Complete task details with output
- """
- print(f'🚀 Fast monitoring task {task_id}...')
-
- start_time = time.time()
- step_count = 0
- last_step_time = start_time
-
- # Faster polling for quick tasks
- poll_interval = 1 # Check every second for fast tasks
-
- while True:
- response = _request_with_retry('get', f'{BASE_URL}/task/{task_id}', headers=HEADERS)
- details = response.json()
- status = details['status']
-
- # Show progress with timing
- current_steps = len(details.get('steps', []))
- elapsed = time.time() - start_time
-
- # Build status message
- if current_steps > step_count:
- step_time = time.time() - last_step_time
- last_step_time = time.time()
- step_count = current_steps
- step_msg = f'🔥 Step {current_steps} | ⚡ {step_time:.1f}s | Total: {elapsed:.1f}s'
- else:
- if status == 'running':
- step_msg = f'🚀 Step {current_steps} | ⏱️ {elapsed:.1f}s | Fast processing...'
- else:
- step_msg = f'🚀 Step {current_steps} | ⏱️ {elapsed:.1f}s | Status: {status}'
-
- # Clear line and show progress
- print(f'\r{step_msg:<80}', end='', flush=True)
-
- # Check completion
- if status == 'finished':
- total_time = time.time() - start_time
- if current_steps > 0:
- avg_msg = f'⚡ Average: {total_time / current_steps:.1f}s per step'
- else:
- avg_msg = '⚡ No steps recorded'
- print(f'\r🏁 Task completed in {total_time:.1f}s! {avg_msg}' + ' ' * 20)
- return details
-
- elif status in ['failed', 'stopped']:
- print(f'\r❌ Task {status} after {elapsed:.1f}s' + ' ' * 30)
- return details
-
- time.sleep(poll_interval)
-
-
-def run_speed_comparison():
- """Run multiple tasks to compare speed vs accuracy."""
- print('\n🏃‍♂️ Speed Comparison Demo')
- print('=' * 40)
-
- tasks = [
- 'Go to ProductHunt and roast the top product like a sarcastic tech reviewer',
- 'Visit Reddit r/ProgrammerHumor and summarize the top post as a dramatic news story',
- "Check GitHub trending and write a conspiracy theory about why everyone's switching to Rust",
- ]
-
- results = []
-
- for i, task in enumerate(tasks, 1):
- print(f'\n📝 Fast Task {i}/{len(tasks)}')
- print(f'Task: {task}')
-
- start = time.time()
- task_id = create_fast_task(task)
- result = monitor_fast_task(task_id)
- end = time.time()
-
- results.append(
- {
- 'task': task,
- 'duration': end - start,
- 'steps': len(result.get('steps', [])),
- 'status': result['status'],
- 'output': result.get('output', '')[:100] + '...' if result.get('output') else 'No output',
- }
- )
-
- # Summary
- print('\n📊 Speed Summary')
- print('=' * 50)
- total_time = sum(r['duration'] for r in results)
- total_steps = sum(r['steps'] for r in results)
-
- for i, result in enumerate(results, 1):
- print(f'Task {i}: {result["duration"]:.1f}s ({result["steps"]} steps) - {result["status"]}')
-
- print(f'\n⚡ Total time: {total_time:.1f}s')
- print(f'🔥 Average per task: {total_time / len(results):.1f}s')
- if total_steps > 0:
- print(f'💨 Average per step: {total_time / total_steps:.1f}s')
- else:
- print('💨 Average per step: N/A (no steps recorded)')
-
-
-def main():
- """Demonstrate ultra-fast cloud automation."""
- print('⚡ Browser Use Cloud - Ultra-Fast Mode with Gemini Flash')
- print('=' * 60)
-
- print('🎯 Configuration Benefits:')
- print('• Gemini Flash: $0.01 per step (cheapest)')
- print('• No proxy: 30% faster execution')
- print('• No highlighting: Better performance')
- print('• Optimized viewport: Faster rendering')
-
- try:
- # Single fast task
- print('\n🚀 Single Fast Task Demo')
- print('-' * 30)
-
- task = """
- Go to Hacker News (news.ycombinator.com) and get the top 3 articles from the front page.
-
- Then, write a funny tech news segment in the style of Fireship YouTube channel:
- - Be sarcastic and witty about tech trends
- - Use developer humor and memes
- - Make fun of common programming struggles
- - Include phrases like "And yes, it runs on JavaScript" or "Plot twist: it's written in Rust"
- - Keep it under 250 words but make it entertaining
- - Structure it like a news anchor delivering breaking tech news
-
- Make each story sound dramatic but also hilarious, like you're reporting on the most important events in human history.
- """
- task_id = create_fast_task(task)
- result = monitor_fast_task(task_id)
-
- print(f'\n📊 Result: {result.get("output", "No output")}')
-
- # Show execution URLs
- if result.get('live_url'):
- print(f'\n🔗 Live Preview: {result["live_url"]}')
- if result.get('public_share_url'):
- print(f'🌐 Share URL: {result["public_share_url"]}')
- elif result.get('share_url'):
- print(f'🌐 Share URL: {result["share_url"]}')
-
- # Optional: Run speed comparison with --compare flag
- parser = argparse.ArgumentParser(description='Fast mode demo with Gemini Flash')
- parser.add_argument('--compare', action='store_true', help='Run speed comparison with 3 tasks')
- args = parser.parse_args()
-
- if args.compare:
- print('\n🏃‍♂️ Running speed comparison...')
- run_speed_comparison()
-
- except requests.exceptions.RequestException as e:
- print(f'❌ API Error: {e}')
- except Exception as e:
- print(f'❌ Error: {e}')
-
-
-if __name__ == '__main__':
- main()
diff --git a/examples/cloud/03_structured_output.py b/examples/cloud/03_structured_output.py
deleted file mode 100644
index cbe73ac11..000000000
--- a/examples/cloud/03_structured_output.py
+++ /dev/null
@@ -1,362 +0,0 @@
-"""
-Cloud Example 3: Structured JSON Output 📋
-==========================================
-
-This example demonstrates how to get structured, validated JSON output:
-- Define Pydantic schemas for type safety
-- Extract structured data from websites
-- Validate and parse JSON responses
-- Handle different data types and nested structures
-
-Perfect for: Data extraction, API integration, structured analysis
-
-Cost: ~$0.06 (1 task + 5-6 steps with GPT-4.1 mini)
-"""
-
-import argparse
-import json
-import os
-import time
-from typing import Any
-
-import requests
-from pydantic import BaseModel, Field, ValidationError
-from requests.exceptions import RequestException
-
-# Configuration
-API_KEY = os.getenv('BROWSER_USE_API_KEY')
-if not API_KEY:
- raise ValueError(
- 'Please set BROWSER_USE_API_KEY environment variable. You can also create an API key at https://cloud.browser-use.com/new-api-key'
- )
-
-BASE_URL = os.getenv('BROWSER_USE_BASE_URL', 'https://api.browser-use.com/api/v1')
-TIMEOUT = int(os.getenv('BROWSER_USE_TIMEOUT', '30'))
-HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
-
-
-def _request_with_retry(method: str, url: str, **kwargs) -> requests.Response:
- """Make HTTP request with timeout and retry logic."""
- kwargs.setdefault('timeout', TIMEOUT)
-
- for attempt in range(3):
- try:
- response = requests.request(method, url, **kwargs)
- response.raise_for_status()
- return response
- except RequestException as e:
- if attempt == 2: # Last attempt
- raise
- sleep_time = 2**attempt
- print(f'⚠️ Request failed (attempt {attempt + 1}/3), retrying in {sleep_time}s: {e}')
- time.sleep(sleep_time)
-
- raise RuntimeError('Unexpected error in retry logic')
-
-
-# Define structured output schemas using Pydantic
-class NewsArticle(BaseModel):
- """Schema for a news article."""
-
- title: str = Field(description='The headline of the article')
- summary: str = Field(description='Brief summary of the article')
- url: str = Field(description='Direct link to the article')
- published_date: str | None = Field(description='Publication date if available')
- category: str | None = Field(description='Article category/section')
-
-
-class NewsResponse(BaseModel):
- """Schema for multiple news articles."""
-
- articles: list[NewsArticle] = Field(description='List of news articles')
- source_website: str = Field(description='The website where articles were found')
- extracted_at: str = Field(description='When the data was extracted')
-
-
-class ProductInfo(BaseModel):
- """Schema for product information."""
-
- name: str = Field(description='Product name')
- price: float = Field(description='Product price in USD')
- rating: float | None = Field(description='Average rating (0-5 scale)')
- availability: str = Field(description='Stock status (in stock, out of stock, etc.)')
- description: str = Field(description='Product description')
-
-
-class CompanyInfo(BaseModel):
- """Schema for company information."""
-
- name: str = Field(description='Company name')
- stock_symbol: str | None = Field(description='Stock ticker symbol')
- market_cap: str | None = Field(description='Market capitalization')
- industry: str = Field(description='Primary industry')
- headquarters: str = Field(description='Headquarters location')
- founded_year: int | None = Field(description='Year founded')
-
-
-def create_structured_task(instructions: str, schema_model: type[BaseModel], **kwargs) -> str:
- """
- Create a task that returns structured JSON output.
-
- Args:
- instructions: Task description
- schema_model: Pydantic model defining the expected output structure
- **kwargs: Additional task parameters
-
- Returns:
- task_id: Unique identifier for the created task
- """
- print(f'📝 Creating structured task: {instructions}')
- print(f'🏗️ Expected schema: {schema_model.__name__}')
-
- # Generate JSON schema from Pydantic model
- json_schema = schema_model.model_json_schema()
-
- payload = {
- 'task': instructions,
- 'structured_output_json': json.dumps(json_schema),
- 'llm_model': 'gpt-4.1-mini',
- 'max_agent_steps': 15,
- 'enable_public_share': True, # Enable shareable execution URLs
- **kwargs,
- }
-
- response = _request_with_retry('post', f'{BASE_URL}/run-task', headers=HEADERS, json=payload)
-
- task_id = response.json()['id']
- print(f'✅ Structured task created: {task_id}')
- return task_id
-
-
-def wait_for_structured_completion(task_id: str, max_wait_time: int = 300) -> dict[str, Any]:
- """Wait for task completion and return the result."""
- print(f'⏳ Waiting for structured output (max {max_wait_time}s)...')
-
- start_time = time.time()
-
- while True:
- response = _request_with_retry('get', f'{BASE_URL}/task/{task_id}/status', headers=HEADERS)
- status = response.json()
- elapsed = time.time() - start_time
-
- # Check for timeout
- if elapsed > max_wait_time:
- print(f'\r⏰ Task timeout after {max_wait_time}s - stopping wait' + ' ' * 30)
- # Get final details before timeout
- details_response = _request_with_retry('get', f'{BASE_URL}/task/{task_id}', headers=HEADERS)
- details = details_response.json()
- return details
-
- # Get step count from full details for better progress tracking
- details_response = _request_with_retry('get', f'{BASE_URL}/task/{task_id}', headers=HEADERS)
- details = details_response.json()
- steps = len(details.get('steps', []))
-
- # Build status message
- if status == 'running':
- status_msg = f'📋 Structured task | Step {steps} | ⏱️ {elapsed:.0f}s | 🔄 Extracting...'
- else:
- status_msg = f'📋 Structured task | Step {steps} | ⏱️ {elapsed:.0f}s | Status: {status}'
-
- # Clear line and show status
- print(f'\r{status_msg:<80}', end='', flush=True)
-
- if status == 'finished':
- print(f'\r✅ Structured data extracted! ({steps} steps in {elapsed:.1f}s)' + ' ' * 20)
- return details
-
- elif status in ['failed', 'stopped']:
- print(f'\r❌ Task {status} after {steps} steps' + ' ' * 30)
- return details
-
- time.sleep(3)
-
-
-def validate_and_display_output(output: str, schema_model: type[BaseModel]):
- """
- Validate the JSON output against the schema and display results.
-
- Args:
- output: Raw JSON string from the task
- schema_model: Pydantic model for validation
- """
- print('\n📊 Structured Output Analysis')
- print('=' * 40)
-
- try:
- # Parse and validate the JSON
- parsed_data = schema_model.model_validate_json(output)
- print('✅ JSON validation successful!')
-
- # Pretty print the structured data
- print('\n📋 Parsed Data:')
- print('-' * 20)
- print(parsed_data.model_dump_json(indent=2))
-
- # Display specific fields based on model type
- if isinstance(parsed_data, NewsResponse):
- print(f'\n📰 Found {len(parsed_data.articles)} articles from {parsed_data.source_website}')
- for i, article in enumerate(parsed_data.articles[:3], 1):
- print(f'\n{i}. {article.title}')
- print(f' Summary: {article.summary[:100]}...')
- print(f' URL: {article.url}')
-
- elif isinstance(parsed_data, ProductInfo):
- print(f'\n🛍️ Product: {parsed_data.name}')
- print(f' Price: ${parsed_data.price}')
- print(f' Rating: {parsed_data.rating}/5' if parsed_data.rating else ' Rating: N/A')
- print(f' Status: {parsed_data.availability}')
-
- elif isinstance(parsed_data, CompanyInfo):
- print(f'\n🏢 Company: {parsed_data.name}')
- print(f' Industry: {parsed_data.industry}')
- print(f' Headquarters: {parsed_data.headquarters}')
- if parsed_data.founded_year:
- print(f' Founded: {parsed_data.founded_year}')
-
- return parsed_data
-
- except ValidationError as e:
- print('❌ JSON validation failed!')
- print(f'Errors: {e}')
- print(f'\nRaw output: {output[:500]}...')
- return None
-
- except json.JSONDecodeError as e:
- print('❌ Invalid JSON format!')
- print(f'Error: {e}')
- print(f'\nRaw output: {output[:500]}...')
- return None
-
-
-def demo_news_extraction():
- """Demo: Extract structured news data."""
- print('\n📰 Demo 1: News Article Extraction')
- print('-' * 40)
-
- task = """
- Go to a major news website (like BBC, CNN, or Reuters) and extract information
- about the top 3 news articles. For each article, get the title, summary, URL,
- and any other available metadata.
- """
-
- task_id = create_structured_task(task, NewsResponse)
- result = wait_for_structured_completion(task_id)
-
- if result.get('output'):
- parsed_result = validate_and_display_output(result['output'], NewsResponse)
-
- # Show execution URLs
- if result.get('live_url'):
- print(f'\n🔗 Live Preview: {result["live_url"]}')
- if result.get('public_share_url'):
- print(f'🌐 Share URL: {result["public_share_url"]}')
- elif result.get('share_url'):
- print(f'🌐 Share URL: {result["share_url"]}')
-
- return parsed_result
- else:
- print('❌ No structured output received')
- return None
-
-
-def demo_product_extraction():
- """Demo: Extract structured product data."""
- print('\n🛍️ Demo 2: Product Information Extraction')
- print('-' * 40)
-
- task = """
- Go to Amazon and search for 'wireless headphones'. Find the first product result
- and extract detailed information including name, price, rating, availability,
- and description.
- """
-
- task_id = create_structured_task(task, ProductInfo)
- result = wait_for_structured_completion(task_id)
-
- if result.get('output'):
- parsed_result = validate_and_display_output(result['output'], ProductInfo)
-
- # Show execution URLs
- if result.get('live_url'):
- print(f'\n🔗 Live Preview: {result["live_url"]}')
- if result.get('public_share_url'):
- print(f'🌐 Share URL: {result["public_share_url"]}')
- elif result.get('share_url'):
- print(f'🌐 Share URL: {result["share_url"]}')
-
- return parsed_result
- else:
- print('❌ No structured output received')
- return None
-
-
-def demo_company_extraction():
- """Demo: Extract structured company data."""
- print('\n🏢 Demo 3: Company Information Extraction')
- print('-' * 40)
-
- task = """
- Go to a financial website and look up information about Apple Inc.
- Extract company details including name, stock symbol, market cap,
- industry, headquarters, and founding year.
- """
-
- task_id = create_structured_task(task, CompanyInfo)
- result = wait_for_structured_completion(task_id)
-
- if result.get('output'):
- parsed_result = validate_and_display_output(result['output'], CompanyInfo)
-
- # Show execution URLs
- if result.get('live_url'):
- print(f'\n🔗 Live Preview: {result["live_url"]}')
- if result.get('public_share_url'):
- print(f'🌐 Share URL: {result["public_share_url"]}')
- elif result.get('share_url'):
- print(f'🌐 Share URL: {result["share_url"]}')
-
- return parsed_result
- else:
- print('❌ No structured output received')
- return None
-
-
-def main():
- """Demonstrate structured output extraction."""
- print('📋 Browser Use Cloud - Structured JSON Output')
- print('=' * 50)
-
- print('🎯 Features:')
- print('• Type-safe Pydantic schemas')
- print('• Automatic JSON validation')
- print('• Structured data extraction')
- print('• Multiple output formats')
-
- try:
- # Parse command line arguments
- parser = argparse.ArgumentParser(description='Structured output extraction demo')
- parser.add_argument('--demo', choices=['news', 'product', 'company', 'all'], default='news', help='Which demo to run')
- args = parser.parse_args()
-
- print(f'\n🔍 Running {args.demo} demo(s)...')
-
- if args.demo == 'news':
- demo_news_extraction()
- elif args.demo == 'product':
- demo_product_extraction()
- elif args.demo == 'company':
- demo_company_extraction()
- elif args.demo == 'all':
- demo_news_extraction()
- demo_product_extraction()
- demo_company_extraction()
-
- except requests.exceptions.RequestException as e:
- print(f'❌ API Error: {e}')
- except Exception as e:
- print(f'❌ Error: {e}')
-
-
-if __name__ == '__main__':
- main()
diff --git a/examples/cloud/04_proxy_usage.py b/examples/cloud/04_proxy_usage.py
deleted file mode 100644
index 71dca7975..000000000
--- a/examples/cloud/04_proxy_usage.py
+++ /dev/null
@@ -1,331 +0,0 @@
-"""
-Cloud Example 4: Proxy Usage 🌍
-===============================
-
-This example demonstrates reliable proxy usage scenarios:
-- Different country proxies for geo-restrictions
-- IP address and location verification
-- Region-specific content access (streaming, news)
-- Search result localization by country
-- Mobile/residential proxy benefits
-
-Perfect for: Geo-restricted content, location testing, regional analysis
-
-Cost: ~$0.08 (1 task + 6-8 steps with proxy enabled)
-"""
-
-import argparse
-import os
-import time
-from typing import Any
-
-import requests
-from requests.exceptions import RequestException
-
-# Configuration
-API_KEY = os.getenv('BROWSER_USE_API_KEY')
-if not API_KEY:
- raise ValueError(
- 'Please set BROWSER_USE_API_KEY environment variable. You can also create an API key at https://cloud.browser-use.com/new-api-key'
- )
-
-BASE_URL = os.getenv('BROWSER_USE_BASE_URL', 'https://api.browser-use.com/api/v1')
-TIMEOUT = int(os.getenv('BROWSER_USE_TIMEOUT', '30'))
-HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
-
-
-def _request_with_retry(method: str, url: str, **kwargs) -> requests.Response:
- """Make HTTP request with timeout and retry logic."""
- kwargs.setdefault('timeout', TIMEOUT)
-
- for attempt in range(3):
- try:
- response = requests.request(method, url, **kwargs)
- response.raise_for_status()
- return response
- except RequestException as e:
- if attempt == 2: # Last attempt
- raise
- sleep_time = 2**attempt
- print(f'⚠️ Request failed (attempt {attempt + 1}/3), retrying in {sleep_time}s: {e}')
- time.sleep(sleep_time)
-
- raise RuntimeError('Unexpected error in retry logic')
-
-
-def create_task_with_proxy(instructions: str, country_code: str = 'us') -> str:
- """
- Create a task with proxy enabled from a specific country.
-
- Args:
- instructions: Task description
- country_code: Proxy country ('us', 'fr', 'it', 'jp', 'au', 'de', 'fi', 'ca')
-
- Returns:
- task_id: Unique identifier for the created task
- """
- print(f'🌍 Creating task with {country_code.upper()} proxy')
- print(f'📝 Task: {instructions}')
-
- payload = {
- 'task': instructions,
- 'llm_model': 'gpt-4.1-mini',
- # Proxy configuration
- 'use_proxy': True, # Required for captcha solving
- 'proxy_country_code': country_code, # Choose proxy location
- # Standard settings
- 'use_adblock': True, # Block ads for faster loading
- 'highlight_elements': True, # Keep highlighting for visibility
- 'max_agent_steps': 15,
- # Enable sharing for viewing execution
- 'enable_public_share': True, # Get shareable URLs
- }
-
- response = _request_with_retry('post', f'{BASE_URL}/run-task', headers=HEADERS, json=payload)
-
- task_id = response.json()['id']
- print(f'✅ Task created with {country_code.upper()} proxy: {task_id}')
- return task_id
-
-
-def test_ip_location(country_code: str) -> dict[str, Any]:
- """Test IP address and location detection with proxy."""
- task = """
- Go to whatismyipaddress.com and tell me:
- 1. The detected IP address
- 2. The detected country/location
- 3. The ISP/organization
- 4. Any other location details shown
-
- Please be specific about what you see on the page.
- """
-
- task_id = create_task_with_proxy(task, country_code)
- return wait_for_completion(task_id)
-
-
-def test_geo_restricted_content(country_code: str) -> dict[str, Any]:
- """Test access to geo-restricted content."""
- task = """
- Go to a major news website (like BBC, CNN, or local news) and check:
- 1. What content is available
- 2. Any geo-restriction messages
- 3. Local/regional content differences
- 4. Language or currency preferences shown
-
- Note any differences from what you might expect.
- """
-
- task_id = create_task_with_proxy(task, country_code)
- return wait_for_completion(task_id)
-
-
-def test_streaming_service_access(country_code: str) -> dict[str, Any]:
- """Test access to region-specific streaming content."""
- task = """
- Go to a major streaming service website (like Netflix, YouTube, or BBC iPlayer)
- and check what content or messaging appears.
-
- Report:
- 1. What homepage content is shown
- 2. Any geo-restriction messages or content differences
- 3. Available content regions or language options
- 4. Any pricing or availability differences
-
- Note: Don't try to log in, just observe the publicly available content.
- """
-
- task_id = create_task_with_proxy(task, country_code)
- return wait_for_completion(task_id)
-
-
-def test_search_results_by_location(country_code: str) -> dict[str, Any]:
- """Test how search results vary by location."""
- task = """
- Go to Google and search for "best restaurants near me" or "local news".
-
- Report:
- 1. What local results appear
- 2. The detected location in search results
- 3. Any location-specific content or ads
- 4. Language preferences
-
- This will show how search results change based on proxy location.
- """
-
- task_id = create_task_with_proxy(task, country_code)
- return wait_for_completion(task_id)
-
-
-def wait_for_completion(task_id: str) -> dict[str, Any]:
- """Wait for task completion and return results."""
- print(f'⏳ Waiting for task {task_id} to complete...')
-
- start_time = time.time()
-
- while True:
- response = _request_with_retry('get', f'{BASE_URL}/task/{task_id}', headers=HEADERS)
- details = response.json()
-
- status = details['status']
- steps = len(details.get('steps', []))
- elapsed = time.time() - start_time
-
- # Build status message
- if status == 'running':
- status_msg = f'🌍 Proxy task | Step {steps} | ⏱️ {elapsed:.0f}s | 🤖 Processing...'
- else:
- status_msg = f'🌍 Proxy task | Step {steps} | ⏱️ {elapsed:.0f}s | Status: {status}'
-
- # Clear line and show status
- print(f'\r{status_msg:<80}', end='', flush=True)
-
- if status == 'finished':
- print(f'\r✅ Task completed in {steps} steps! ({elapsed:.1f}s total)' + ' ' * 20)
- return details
-
- elif status in ['failed', 'stopped']:
- print(f'\r❌ Task {status} after {steps} steps' + ' ' * 30)
- return details
-
- time.sleep(3)
-
-
-def demo_proxy_countries():
- """Demonstrate proxy usage across different countries."""
- print('\n🌍 Demo 1: Proxy Countries Comparison')
- print('-' * 45)
-
- countries = [('us', 'United States'), ('de', 'Germany'), ('jp', 'Japan'), ('au', 'Australia')]
-
- results = {}
-
- for code, name in countries:
- print(f'\n🌍 Testing {name} ({code.upper()}) proxy:')
- print('=' * 40)
-
- result = test_ip_location(code)
- results[code] = result
-
- if result.get('output'):
- print(f'📍 Location Result: {result["output"][:200]}...')
-
- # Show execution URLs
- if result.get('live_url'):
- print(f'🔗 Live Preview: {result["live_url"]}')
- if result.get('public_share_url'):
- print(f'🌐 Share URL: {result["public_share_url"]}')
- elif result.get('share_url'):
- print(f'🌐 Share URL: {result["share_url"]}')
-
- print('-' * 40)
- time.sleep(2) # Brief pause between tests
-
- # Summary comparison
- print('\n📊 Proxy Location Summary:')
- print('=' * 30)
- for code, result in results.items():
- status = result.get('status', 'unknown')
- print(f'{code.upper()}: {status}')
-
-
-def demo_geo_restrictions():
- """Demonstrate geo-restriction bypass."""
- print('\n🚫 Demo 2: Geo-Restriction Testing')
- print('-' * 40)
-
- # Test from different locations
- locations = [('us', 'US content'), ('de', 'European content')]
-
- for code, description in locations:
- print(f'\n🌍 Testing {description} with {code.upper()} proxy:')
- result = test_geo_restricted_content(code)
-
- if result.get('output'):
- print(f'📰 Content Access: {result["output"][:200]}...')
-
- time.sleep(2)
-
-
-def demo_streaming_access():
- """Demonstrate streaming service access with different proxies."""
- print('\n📺 Demo 3: Streaming Service Access')
- print('-' * 40)
-
- locations = [('us', 'US'), ('de', 'Germany')]
-
- for code, name in locations:
- print(f'\n🌍 Testing streaming access from {name}:')
- result = test_streaming_service_access(code)
-
- if result.get('output'):
- print(f'📺 Access Result: {result["output"][:200]}...')
-
- time.sleep(2)
-
-
-def demo_search_localization():
- """Demonstrate search result localization."""
- print('\n🔍 Demo 4: Search Localization')
- print('-' * 35)
-
- locations = [('us', 'US'), ('de', 'Germany')]
-
- for code, name in locations:
- print(f'\n🌍 Testing search results from {name}:')
- result = test_search_results_by_location(code)
-
- if result.get('output'):
- print(f'🔍 Search Results: {result["output"][:200]}...')
-
- time.sleep(2)
-
-
-def main():
- """Demonstrate comprehensive proxy usage."""
- print('🌍 Browser Use Cloud - Proxy Usage Examples')
- print('=' * 50)
-
- print('🎯 Proxy Benefits:')
- print('• Bypass geo-restrictions')
- print('• Test location-specific content')
- print('• Access region-locked websites')
- print('• Mobile/residential IP addresses')
- print('• Verify IP geolocation')
-
- print('\n🌐 Available Countries:')
- countries = ['🇺🇸 US', '🇫🇷 France', '🇮🇹 Italy', '🇯🇵 Japan', '🇦🇺 Australia', '🇩🇪 Germany', '🇫🇮 Finland', '🇨🇦 Canada']
- print(' • '.join(countries))
-
- try:
- # Parse command line arguments
- parser = argparse.ArgumentParser(description='Proxy usage examples')
- parser.add_argument(
- '--demo', choices=['countries', 'geo', 'streaming', 'search', 'all'], default='countries', help='Which demo to run'
- )
- args = parser.parse_args()
-
- print(f'\n🔍 Running {args.demo} demo(s)...')
-
- if args.demo == 'countries':
- demo_proxy_countries()
- elif args.demo == 'geo':
- demo_geo_restrictions()
- elif args.demo == 'streaming':
- demo_streaming_access()
- elif args.demo == 'search':
- demo_search_localization()
- elif args.demo == 'all':
- demo_proxy_countries()
- demo_geo_restrictions()
- demo_streaming_access()
- demo_search_localization()
-
- except requests.exceptions.RequestException as e:
- print(f'❌ API Error: {e}')
- except Exception as e:
- print(f'❌ Error: {e}')
-
-
-if __name__ == '__main__':
- main()
diff --git a/examples/cloud/05_search_api.py b/examples/cloud/05_search_api.py
deleted file mode 100644
index 64c01dc04..000000000
--- a/examples/cloud/05_search_api.py
+++ /dev/null
@@ -1,355 +0,0 @@
-"""
-Cloud Example 5: Search API (Beta) 🔍
-=====================================
-
-This example demonstrates the Browser Use Search API (BETA):
-- Simple search: Search Google and extract from multiple results
-- URL search: Extract specific content from a target URL
-- Deep navigation through websites (depth parameter)
-- Real-time content extraction vs cached results
-
-Perfect for: Content extraction, research, competitive analysis
-"""
-
-import argparse
-import asyncio
-import json
-import os
-import time
-from typing import Any
-
-import aiohttp
-
-# Configuration
-API_KEY = os.getenv('BROWSER_USE_API_KEY')
-if not API_KEY:
- raise ValueError(
- 'Please set BROWSER_USE_API_KEY environment variable. You can also create an API key at https://cloud.browser-use.com/new-api-key'
- )
-
-BASE_URL = os.getenv('BROWSER_USE_BASE_URL', 'https://api.browser-use.com/api/v1')
-TIMEOUT = int(os.getenv('BROWSER_USE_TIMEOUT', '30'))
-HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
-
-
-async def simple_search(query: str, max_websites: int = 5, depth: int = 2) -> dict[str, Any]:
- """
- Search Google and extract content from multiple top results.
-
- Args:
- query: Search query to process
- max_websites: Number of websites to process (1-10)
- depth: How deep to navigate (2-5)
-
- Returns:
- Dictionary with results from multiple websites
- """
- # Validate input parameters
- max_websites = max(1, min(max_websites, 10)) # Clamp to 1-10
- depth = max(2, min(depth, 5)) # Clamp to 2-5
-
- start_time = time.time()
-
- print(f"🔍 Simple Search: '{query}'")
- print(f'📊 Processing {max_websites} websites at depth {depth}')
- print(f'💰 Estimated cost: {depth * max_websites}¢')
-
- payload = {'query': query, 'max_websites': max_websites, 'depth': depth}
-
- timeout = aiohttp.ClientTimeout(total=TIMEOUT)
- connector = aiohttp.TCPConnector(limit=10) # Limit concurrent connections
-
- async with aiohttp.ClientSession(timeout=timeout, connector=connector) as session:
- async with session.post(f'{BASE_URL}/simple-search', json=payload, headers=HEADERS) as response:
- elapsed = time.time() - start_time
- if response.status == 200:
- try:
- result = await response.json()
- print(f'✅ Found results from {len(result.get("results", []))} websites in {elapsed:.1f}s')
- return result
- except (aiohttp.ContentTypeError, json.JSONDecodeError) as e:
- error_text = await response.text()
- print(f'❌ Invalid JSON response: {e} (after {elapsed:.1f}s)')
- return {'error': 'Invalid JSON', 'details': error_text}
- else:
- error_text = await response.text()
- print(f'❌ Search failed: {response.status} - {error_text} (after {elapsed:.1f}s)')
- return {'error': f'HTTP {response.status}', 'details': error_text}
-
-
-async def search_url(url: str, query: str, depth: int = 2) -> dict[str, Any]:
- """
- Extract specific content from a target URL.
-
- Args:
- url: Target URL to extract from
- query: What specific content to look for
- depth: How deep to navigate (2-5)
-
- Returns:
- Dictionary with extracted content
- """
- # Validate input parameters
- depth = max(2, min(depth, 5)) # Clamp to 2-5
-
- start_time = time.time()
-
- print(f'🎯 URL Search: {url}')
- print(f"🔍 Looking for: '{query}'")
- print(f'📊 Navigation depth: {depth}')
- print(f'💰 Estimated cost: {depth}¢')
-
- payload = {'url': url, 'query': query, 'depth': depth}
-
- timeout = aiohttp.ClientTimeout(total=TIMEOUT)
- connector = aiohttp.TCPConnector(limit=10) # Limit concurrent connections
-
- async with aiohttp.ClientSession(timeout=timeout, connector=connector) as session:
- async with session.post(f'{BASE_URL}/search-url', json=payload, headers=HEADERS) as response:
- elapsed = time.time() - start_time
- if response.status == 200:
- try:
- result = await response.json()
- print(f'✅ Extracted content from {result.get("url", "website")} in {elapsed:.1f}s')
- return result
- except (aiohttp.ContentTypeError, json.JSONDecodeError) as e:
- error_text = await response.text()
- print(f'❌ Invalid JSON response: {e} (after {elapsed:.1f}s)')
- return {'error': 'Invalid JSON', 'details': error_text}
- else:
- error_text = await response.text()
- print(f'❌ URL search failed: {response.status} - {error_text} (after {elapsed:.1f}s)')
- return {'error': f'HTTP {response.status}', 'details': error_text}
-
-
-def display_simple_search_results(results: dict[str, Any]):
- """Display simple search results in a readable format."""
- if 'error' in results:
- print(f'❌ Error: {results["error"]}')
- return
-
- websites = results.get('results', [])
-
- print(f'\n📋 Search Results ({len(websites)} websites)')
- print('=' * 50)
-
- for i, site in enumerate(websites, 1):
- url = site.get('url', 'Unknown URL')
- content = site.get('content', 'No content')
-
- print(f'\n{i}. 🌐 {url}')
- print('-' * 40)
-
- # Show first 300 chars of content
- if len(content) > 300:
- print(f'{content[:300]}...')
- print(f'[Content truncated - {len(content)} total characters]')
- else:
- print(content)
-
- # Show execution URLs if available
- if results.get('live_url'):
- print(f'\n🔗 Live Preview: {results["live_url"]}')
- if results.get('public_share_url'):
- print(f'🌐 Share URL: {results["public_share_url"]}')
- elif results.get('share_url'):
- print(f'🌐 Share URL: {results["share_url"]}')
-
-
-def display_url_search_results(results: dict[str, Any]):
- """Display URL search results in a readable format."""
- if 'error' in results:
- print(f'❌ Error: {results["error"]}')
- return
-
- url = results.get('url', 'Unknown URL')
- content = results.get('content', 'No content')
-
- print(f'\n📄 Extracted Content from: {url}')
- print('=' * 60)
- print(content)
-
- # Show execution URLs if available
- if results.get('live_url'):
- print(f'\n🔗 Live Preview: {results["live_url"]}')
- if results.get('public_share_url'):
- print(f'🌐 Share URL: {results["public_share_url"]}')
- elif results.get('share_url'):
- print(f'🌐 Share URL: {results["share_url"]}')
-
-
-async def demo_news_search():
- """Demo: Search for latest news across multiple sources."""
- print('\n📰 Demo 1: Latest News Search')
- print('-' * 35)
-
- demo_start = time.time()
- query = 'latest developments in artificial intelligence 2024'
- results = await simple_search(query, max_websites=4, depth=2)
- demo_elapsed = time.time() - demo_start
-
- display_simple_search_results(results)
- print(f'\n⏱️ Total demo time: {demo_elapsed:.1f}s')
-
- return results
-
-
-async def demo_competitive_analysis():
- """Demo: Analyze competitor websites."""
- print('\n🏢 Demo 2: Competitive Analysis')
- print('-' * 35)
-
- query = 'browser automation tools comparison features pricing'
- results = await simple_search(query, max_websites=3, depth=3)
- display_simple_search_results(results)
-
- return results
-
-
-async def demo_deep_website_analysis():
- """Demo: Deep analysis of a specific website."""
- print('\n🎯 Demo 3: Deep Website Analysis')
- print('-' * 35)
-
- demo_start = time.time()
- url = 'https://docs.browser-use.com'
- query = 'Browser Use features, pricing, and API capabilities'
- results = await search_url(url, query, depth=3)
- demo_elapsed = time.time() - demo_start
-
- display_url_search_results(results)
- print(f'\n⏱️ Total demo time: {demo_elapsed:.1f}s')
-
- return results
-
-
-async def demo_product_research():
- """Demo: Product research and comparison."""
- print('\n🛍️ Demo 4: Product Research')
- print('-' * 30)
-
- query = 'best wireless headphones 2024 reviews comparison'
- results = await simple_search(query, max_websites=5, depth=2)
- display_simple_search_results(results)
-
- return results
-
-
-async def demo_real_time_vs_cached():
- """Demo: Show difference between real-time and cached results."""
- print('\n⚡ Demo 5: Real-time vs Cached Data')
- print('-' * 40)
-
- print('🔄 Browser Use Search API benefits:')
- print('• Actually browses websites like a human')
- print('• Gets live, current data (not cached)')
- print('• Navigates deep into sites via clicks')
- print('• Handles JavaScript and dynamic content')
- print('• Accesses pages requiring navigation')
-
- # Example with live data
- query = 'current Bitcoin price USD live'
- results = await simple_search(query, max_websites=3, depth=2)
-
- print('\n💰 Live Bitcoin Price Search Results:')
- display_simple_search_results(results)
-
- return results
-
-
-async def demo_search_depth_comparison():
- """Demo: Compare different search depths."""
- print('\n📊 Demo 6: Search Depth Comparison')
- print('-' * 40)
-
- url = 'https://news.ycombinator.com'
- query = 'trending technology discussions'
-
- depths = [2, 3, 4]
- results = {}
-
- for depth in depths:
- print(f'\n🔍 Testing depth {depth}:')
- result = await search_url(url, query, depth)
- results[depth] = result
-
- if 'content' in result:
- content_length = len(result['content'])
- print(f'📏 Content length: {content_length} characters')
-
- # Brief pause between requests
- await asyncio.sleep(1)
-
- # Summary
- print('\n📊 Depth Comparison Summary:')
- print('-' * 30)
- for depth, result in results.items():
- if 'content' in result:
- length = len(result['content'])
- print(f'Depth {depth}: {length} characters')
- else:
- print(f'Depth {depth}: Error or no content')
-
- return results
-
-
-async def main():
- """Demonstrate comprehensive Search API usage."""
- print('🔍 Browser Use Cloud - Search API (BETA)')
- print('=' * 45)
-
- print('⚠️ Note: This API is in BETA and may change')
- print()
- print('🎯 Search API Features:')
- print('• Real-time website browsing (not cached)')
- print('• Deep navigation through multiple pages')
- print('• Dynamic content and JavaScript handling')
- print('• Multiple result aggregation')
- print('• Cost-effective content extraction')
-
- print('\n💰 Pricing:')
- print('• Simple Search: 1¢ × depth × websites')
- print('• URL Search: 1¢ × depth')
- print('• Example: depth=2, 5 websites = 10¢')
-
- try:
- # Parse command line arguments
- parser = argparse.ArgumentParser(description='Search API (BETA) examples')
- parser.add_argument(
- '--demo',
- choices=['news', 'competitive', 'deep', 'product', 'realtime', 'depth', 'all'],
- default='news',
- help='Which demo to run',
- )
- args = parser.parse_args()
-
- print(f'\n🔍 Running {args.demo} demo(s)...')
-
- if args.demo == 'news':
- await demo_news_search()
- elif args.demo == 'competitive':
- await demo_competitive_analysis()
- elif args.demo == 'deep':
- await demo_deep_website_analysis()
- elif args.demo == 'product':
- await demo_product_research()
- elif args.demo == 'realtime':
- await demo_real_time_vs_cached()
- elif args.demo == 'depth':
- await demo_search_depth_comparison()
- elif args.demo == 'all':
- await demo_news_search()
- await demo_competitive_analysis()
- await demo_deep_website_analysis()
- await demo_product_research()
- await demo_real_time_vs_cached()
- await demo_search_depth_comparison()
-
- except aiohttp.ClientError as e:
- print(f'❌ Network Error: {e}')
- except Exception as e:
- print(f'❌ Error: {e}')
-
-
-if __name__ == '__main__':
- asyncio.run(main())
diff --git a/examples/cloud/README.md b/examples/cloud/README.md
index e2aba21d0..6c2024ac1 100644
--- a/examples/cloud/README.md
+++ b/examples/cloud/README.md
@@ -1,137 +1,28 @@
-# Browser Use Cloud Examples 🚀
+# Browser Use Cloud API V4
-Welcome to the Browser Use Cloud examples! This folder contains progressively complex examples to help you get started with the Browser Use Cloud API quickly and efficiently.
+Run one browser task through the current Cloud API. The example creates a run, polls the lightweight status endpoint, and fetches the result once the run is terminal.
-## 📋 Prerequisites
+## Setup
-1. **API Key**: Get your API key from [cloud.browser-use.com](https://cloud.browser-use.com/new-api-key)
-2. **Python Environment**: Python 3.11+ with dependencies
-3. **Environment Variables**: Configure your API settings
-
-### Quick Setup
+From the repository root:
```bash
-# Create virtual environment and install dependencies (from project root)
-uv venv --python 3.11
-source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync
-
-# Set environment variables
-export BROWSER_USE_API_KEY="your_api_key_here"
-export BROWSER_USE_BASE_URL="https://api.browser-use.com/api/v1" # Optional
-export BROWSER_USE_TIMEOUT="30" # Optional: request timeout in seconds
-
-# Or use .env file (recommended)
cp examples/cloud/env.example .env
-# Edit .env with your values
-
-# Run examples from project root
-python examples/cloud/01_basic_task.py
-```
-
-## 🎯 Examples Overview
-
-### 🚀 Easy Cloud Setup Examples
-
-- **[01_basic_task.py](./01_basic_task.py)** - Your first cloud task (start here!)
-- **[02_fast_mode_gemini.py](./02_fast_mode_gemini.py)** - ⚡ Ultra-fast mode with Gemini Flash & Fireship humor
-- **[03_structured_output.py](./03_structured_output.py)** - Get structured JSON responses
-- **[04_proxy_usage.py](./04_proxy_usage.py)** - 🌍 Proxy for geo-restrictions & captcha solving
-- **[05_search_api.py](./05_search_api.py)** - 🔍 Search API for content extraction (BETA)
-
-## 💰 Cost Optimization Tips
-
-1. **Use Gemini Flash** for fastest/cheapest execution ($0.01/step)
-2. **Disable proxy** when not needed for captcha solving
-3. **Disable element highlighting** for better performance
-4. **Set max_agent_steps** to prevent runaway costs
-5. **Use structured output** to reduce parsing overhead
-6. **Add timeouts and retries** for reliability in production
-7. **Use domain restrictions** when working with secrets
-
-## 🎨 Fast Mode Configuration
-
-For maximum speed and cost efficiency:
-
-```python
-{
- "llm_model": "gemini-2.5-flash",
- "use_proxy": False,
- "highlight_elements": False,
- "use_adblock": True,
- "max_agent_steps": 50
-}
+# Add your API key to .env
+uv run python examples/cloud/01_basic_task.py
```
-## 🔐 Security & Advanced Features
-
-### Using Proxy
-```python
-{
- "use_proxy": True,
- "proxy_country_code": "us", # 'us', 'fr', 'it', 'jp', 'au', 'de', 'fi', 'ca'
-}
-```
-
-### Passing Secrets Securely
-```python
-{
- "secrets": {
- "username": "your_username",
- "password": "your_password",
- "api_key": "your_api_key"
- },
- "allowed_domains": ["*.yoursite.com"] # Recommended with secrets
-}
-```
-
-## 🔍 Search API (BETA)
-
-The Search API extracts content by actually browsing websites (not cached results):
-
-### Simple Search (Multi-site)
-```python
-# Cost: 1¢ × depth × websites
-{
- "query": "latest AI news",
- "max_websites": 5,
- "depth": 2
-}
-```
-
-### URL Search (Single site)
-```python
-# Cost: 1¢ × depth
-{
- "url": "https://example.com",
- "query": "pricing information",
- "depth": 3
-}
-```
-
-## 🔗 Quick Links
-
-- [Cloud API Documentation](https://docs.browser-use.com/cloud)
-- [API Reference](https://docs.browser-use.com/api-reference)
-- [Pricing](https://cloud.browser-use.com/billing)
-- [Discord Community](https://link.browser-use.com/discord)
-
-## 🔧 Production Best Practices
-
-- **Timeouts**: All examples include 30-second timeouts with retry logic
-- **Error Handling**: Comprehensive error catching and status code validation
-- **Security**: Use environment variables, domain restrictions with secrets
-- **Reliability**: Built-in retries for network issues and rate limits
-- **Automation**: CLI arguments instead of interactive prompts for CI/CD
+Create an API key at [cloud.browser-use.com/new-api-key](https://cloud.browser-use.com/new-api-key).
-## 🆘 Support
+## V4 request flow
-Need help?
+The example uses the three endpoints needed for a basic run:
-- 📧 Email: [email protected]
-- 💬 Discord: [Join our community](https://link.browser-use.com/discord)
-- 📖 Docs: <https://docs.browser-use.com>
+1. `POST /api/v4/runs`
+2. `GET /api/v4/runs/{run_id}/status` until the run is `completed`, `failed`, or `cancelled`
+3. `GET /api/v4/runs/{run_id}` for the result, error, and cost
----
+Authentication uses the `X-Browser-Use-API-Key` header. See the live [V4 OpenAPI specification](https://api.browser-use.com/api/v4/openapi.json) for optional models, browser settings, sessions, files, secrets, and judge settings.
-**💡 Pro Tip**: Start with `01_basic_task.py` and work your way up. Each example builds on the previous ones!
+Review usage and credits in [Cloud billing](https://cloud.browser-use.com/billing).
diff --git a/examples/cloud/env.example b/examples/cloud/env.example
index 3fbbcda19..73f1e2ebf 100644
--- a/examples/cloud/env.example
+++ b/examples/cloud/env.example
@@ -1,21 +1,5 @@
-# Browser Use Cloud API Configuration
-# Copy this file to .env and fill in your values
-
-# Required: Your Browser Use Cloud API key
-# Get it from: https://cloud.browser-use.com/new-api-key
+# Create a key at https://cloud.browser-use.com/new-api-key
BROWSER_USE_API_KEY=your_api_key_here
-# Optional: Custom API base URL (for enterprise installations)
-# BROWSER_USE_BASE_URL=https://api.browser-use.com/api/v1
-
-# Optional: Default model preference
-# BROWSER_USE_DEFAULT_MODEL=gemini-2.5-flash
-
-# Optional: Cost limits
-# BROWSER_USE_MAX_COST_PER_TASK=5.0
-
-# Optional: Request timeout (seconds)
-# BROWSER_USE_TIMEOUT=30
-
-# Optional: Logging configuration
-# LOG_LEVEL=INFO
+# Optional: override the API root for an enterprise installation.
+# BROWSER_USE_API_URL=https://api.browser-use.com/api/v4