browsernative

Python client for the Browser Native web scraping API

Lightweight client for scraping, screenshots, and AI analysis via the Browser Native API. Single dependency (requests).

Install

pip install browsernative

Get an API key at bnca.monostate.ai.

Usage

from browsernative import BrowserNativeClient

client = BrowserNativeClient('your-api-key')

# Scrape
result = client.scrape('https://example.com')

# Force a specific scraping method
result = client.scrape('https://example.com', method='lightpanda')

# Screenshot
screenshot = client.screenshot('https://example.com')

# Quick screenshot (faster, no content extraction)
quick = client.quickshot('https://example.com')

# AI Q&A
answer = client.analyze('https://example.com', 'What is this site about?')

Convenience functions

from browsernative import quick_scrape, quick_shot, quick_analyze, bulk_scrape

content = quick_scrape('https://example.com', 'your-api-key')
shot = quick_shot('https://example.com', 'your-api-key')
answer = quick_analyze('https://example.com', 'What is this?', 'your-api-key')

Bulk scraping

urls = ['https://site1.com', 'https://site2.com', 'https://site3.com']

result = client.bulk_scrape(
    urls,
    concurrency=5,
    continue_on_error=True,
    progress_callback=lambda p: print(f"{p['percentage']:.1f}%"),
)

print(f"{result['stats']['successful']}/{result['stats']['total']} succeeded")

Context manager

with BrowserNativeClient('your-api-key') as client:
    result = client.scrape('https://example.com')
    # Session closed automatically

API Reference

Client options

client = BrowserNativeClient(
    api_key='your-api-key',
    base_url='https://bnca-api.fly.dev',  # API endpoint
    timeout=30,                            # Seconds
    retries=2,                             # Retry attempts
    verbose=False,                         # Debug logging
)

Methods

Scrape options

Pass as keyword arguments:

• method -- 'auto', 'direct', 'lightpanda', or 'puppeteer'
• include_screenshot -- Include screenshot in response
• wait_for_selector -- CSS selector to wait for
• user_agent -- Custom user agent

Response shape

{
    'success': True,
    'data': { 'title': ..., 'content': ..., ... },
    'responseTime': 1234,
    'attempt': 1,
}

Browser sessions

Persistent browser sessions with real-time control over WebSocket:

session = client.create_session(mode='auto')

session.goto('https://example.com')
session.click('#login')
session.type('#email', 'user@example.com')
state = session.get_page_state(includeScreenshot=True)
session.screenshot()

# Listen for backend fallback events
session.on('fallback', lambda e: print(f"{e['from']} -> {e['to']}: {e['reason']}"))

session.close()

Modes: auto (LightPanda + Chrome fallback), headless, visual, computer-use.

Computer use mode

For AI agents that control the browser by pixel coordinates:

session = client.create_session(mode='computer-use', screen_width=1280, screen_height=800)

session.goto('https://example.com')
session.click_at(640, 400)
session.type_text('hello world')
session.mouse_move(100, 200)
session.drag(10, 20, 300, 400)
session.scroll_at(640, 400, 'down', 5)
pos = session.get_cursor_position()
size = session.get_screen_size()
screenshot = session.screenshot()

# VNC streaming URL
print(session.vnc_url)

session.close()

Requires websocket-client: pip install websocket-client

Requirements

• Python 3.9+
• requests (installed automatically)
• websocket-client (for browser sessions)

Changelog

See CHANGELOG.md.

License

MIT