Skip to content

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

feat: added examples on how to use the cloud api

Saurav Panda9e108a25f3d7
diff --git a/examples/cloud/01_basic_task.py b/examples/cloud/01_basic_task.py
new file mode 100644
index 000000000..ee4215576
--- /dev/null
+++ b/examples/cloud/01_basic_task.py
@@ -0,0 +1,186 @@
+"""
+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)
+"""
+
+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')
+
+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')
+
+
+def create_task(instructions: str) -> str:
+ """
+ Create a new browser automation task.
+
+ Args:
+ instructions: Natural language description of what the agent should do
+
+ 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 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()
+
+
+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)
+ 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)
+
+ Returns:
+ Complete task details with output
+ """
+ print(f'⏳ Monitoring task {task_id}...')
+
+ 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}')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/examples/cloud/02_fast_mode_gemini.py b/examples/cloud/02_fast_mode_gemini.py
new file mode 100644
index 000000000..5bbf65fe1
--- /dev/null
+++ b/examples/cloud/02_fast_mode_gemini.py
@@ -0,0 +1,260 @@
+"""
+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')
+
+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')
+ print(f'💨 Average per step: {total_time / total_steps:.1f}s')
+
+
+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
new file mode 100644
index 000000000..c9b95b58f
--- /dev/null
+++ b/examples/cloud/03_structured_output.py
@@ -0,0 +1,352 @@
+"""
+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')
+
+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) -> dict[str, Any]:
+ """Wait for task completion and return the result."""
+ print('⏳ Waiting for structured output...')
+
+ 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
+
+ # 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
new file mode 100644
index 000000000..862f33545
--- /dev/null
+++ b/examples/cloud/04_proxy_usage.py
@@ -0,0 +1,329 @@
+"""
+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')
+
+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
new file mode 100644
index 000000000..02e1934e5
--- /dev/null
+++ b/examples/cloud/05_search_api.py
@@ -0,0 +1,342 @@
+"""
+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 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')
+
+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:
+ result = await response.json()
+ print(f'✅ Found results from {len(result.get("results", []))} websites in {elapsed:.1f}s')
+ return result
+ 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:
+ result = await response.json()
+ print(f'✅ Extracted content from {result.get("url", "website")} in {elapsed:.1f}s')
+ return result
+ 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
new file mode 100644
index 000000000..f60c3d5f2
--- /dev/null
+++ b/examples/cloud/README.md
@@ -0,0 +1,137 @@
+# Browser Use Cloud Examples 🚀
+
+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.
+
+## 📋 Prerequisites
+
+1. **API Key**: Get your API key from [cloud.browser-use.com/billing](https://cloud.browser-use.com/billing)
+2. **Python Environment**: Python 3.11+ with dependencies
+3. **Environment Variables**: Configure your API settings
+
+### Quick Setup
+
+```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
+}
+```
+
+## 🔐 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
+
+## 🆘 Support
+
+Need help?
+
+- 📧 Email: [email protected]
+- 💬 Discord: [Join our community](https://link.browser-use.com/discord)
+- 📖 Docs: <https://docs.browser-use.com>
+
+---
+
+**💡 Pro Tip**: Start with `01_basic_task.py` and work your way up. Each example builds on the previous ones!
diff --git a/examples/cloud/env.example b/examples/cloud/env.example
new file mode 100644
index 000000000..7d73866da
--- /dev/null
+++ b/examples/cloud/env.example
@@ -0,0 +1,21 @@
+# 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/billing
+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