Session Management

`client.create_session(enable_proxy=False, rotate_proxy=False, proxy_tier=None, proxy_policy=None, country=None, city=None, block_unproxied=False, cookies=None, session_timeout=None) -> BroSession`

Creates a new session context manager.

Browser coordinates:

Browser window size: (width, height): (1280, 1024)
Viewport frame size: (width, height): (1279, 936)

Arguments:

enable_proxy (boolean, optional): Whether to enable built-in residential proxy routing for this session. Default is False.
rotate_proxy (boolean, optional): If True, the browser will iterate proxy tiers, policies and locations to find a combination that can access the target site. Note: this option may significantly increase proxy bandwidth usage. Default is False.
proxy_tier (string, optional): The quality tier of the residential proxy network.
- "lite" (Default if enable_proxy is enabled): The most affordable residential network.
- "basic": Standard residential network, good for most common anti-bot protections.
- "premium": Higher-quality proxy network with better success rates for strict anti-bot protections.
proxy_policy (string, optional): Defines what type of traffic is routed through the proxy to help optimize bandwidth costs.
- "html_only": Proxies only HTML documents.
- "basic" (Default if enable_proxy is enabled): Proxies HTML, XHR and WebSockets.
- "extended": Proxies everything in basic plus JavaScript files and their child requests.
- "full": Routes all traffic through the proxy including media.
country (string, optional): Target ISO country code for the proxy (e.g., "US", "GB").
city (string, optional): Target city for the proxy. Supported cities depend on the selected country. If not provided, a random location within the selected country will be chosen.
block_unproxied (boolean, optional): If True, any web traffic that is not routed through the proxy (based on your proxy_policy) will be completely blocked instead of bypassing the proxy. Might be useful when you don't want to expose browser IP to website for non-'full' policies. Default is False.
cookies (list of dicts, optional): A list of cookie dictionaries to inject into the new browser session. Each dictionary must contain name, value and domain.
session_timeout (float, optional): Absolute maximum time (in seconds) the session can exist before it self-terminates. Maximum value is 3600.0 (1 hour). Defaults to 3600.0.

Session Statuses:

queued: waiting for an available worker
initializing: a worker was assigned and the browser is starting
idle: ready to accept the next command
busy: currently executing a command
terminated: ended normally, for example by timeout or natural completion
stopped: explicitly stopped by the user
failed: ended due to an unrecoverable error
cancelled: queue wait expired before the session was assigned

Notes:

A session stays alive until you stop it or it expires.
Only one command can run at a time for a session.
A session may remain reusable across many execute calls.

`BroSession` Properties

Every BroSession exposes the following properties reflecting the remote session state:

session.session_id (string): The unique identifier of the session.
session.is_active (boolean): Boolean indicating if the session is currently active and running.
session.status (string): The current status of the session (e.g., "idle", "busy", "queued", "terminated", "stopped", "failed").
session.created_at (string): ISO 8601 timestamp of when the session was created.
session.current_url (string): The URL the browser is currently at.
session.command_id (string, optional): The ID of the command currently being executed (if "busy").
session.error_name (string, optional): The name of the error if the session failed.
session.error_message (string, optional): A descriptive message of the error if the session failed.
session.billing (dict): Dictionary containing detailed billing metrics for the session.
- last_synced_at (string): Timestamp of the last billing sync.
- total_billed (float): Total cost billed for the session.
- breakdown (dict): Cost breakdown by resource.
  - runner (float): Cost for the runner compute.
  - proxy (float): Cost for proxy usage.
  - llm (float): Cost for AI tokens used.
  - grounding (float): Cost for grounding operations.
  - ocr (float): Cost for OCR operations.
session.proxy_usage (dict): Dictionary containing metrics for the proxy network.
- total_traffic_mb (float): Total traffic consumed through the proxy in megabytes.
- total_flows (int): Total number of network flows (connections) made.
- total_errors (int): Total number of proxy connection errors.
- error_rate (float): Percentage of connections that resulted in an error.
- avg_latency_ms (float): Average latency in milliseconds.
- min_latency_ms (float): Minimum latency in milliseconds.
- max_latency_ms (float): Maximum latency in milliseconds.
- median_latency_ms (float): Median latency in milliseconds.
- p95_latency_ms (float): 95th percentile latency in milliseconds.
session.tokens (dict): Dictionary tracking LLM token consumption.
- total (int): Total tokens consumed.
- prompt (int): Total prompt tokens consumed.
- completion (int): Total completion tokens consumed.
session.stream_url (string, optional): Live stream URL for the browser session.
session.video_url (string, optional): Session video URL hosted in the cloud. Note: Video recordings of sessions are retained for 60 days. If a session is older than 60 days, this field will be None.
session.browser_info (dict): Dictionary containing metadata about the actual browser instance executing the session.
- browser_version (string): The underlying browser's version string.
- user_agent (string): The user agent string exposed to websites.
- window_width (int): The dimensions of the entire browser window in pixels.
- window_height (int): The dimensions of the entire browser window in pixels.
- window_x (int): The screen coordinates of the top-left corner of the browser window.
- window_y (int): The screen coordinates of the top-left corner of the browser window.
- viewport_width (int): The dimensions of the inner area displaying the webpage.
- viewport_height (int): The dimensions of the inner area displaying the webpage.
- viewport_x1 (int): The OS screen coordinates bounding the viewport area.
- viewport_y1 (int): The OS screen coordinates bounding the viewport area.
- viewport_x2 (int): The OS screen coordinates bounding the viewport area.
- viewport_y2 (int): The OS screen coordinates bounding the viewport area.

State Example:

python
{
  "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
  "is_active": True,
  "status": "idle",
  "created_at": "2026-05-01T12:00:00Z",
  "current_url": "https://example.com",
  "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "error_name": None,
  "error_message": None,
  "billing": {
    "last_synced_at": "2026-05-01T12:05:00Z",
    "total_billed": 0.05,
    "breakdown": {
      "runner": 0.01,
      "proxy": 0.02,
      "llm": 0.01,
      "grounding": 0.01,
      "ocr": 0.00
    }
  },
  "proxy_usage": {
    "total_traffic_mb": 1.5,
    "total_flows": 45,
    "total_errors": 0,
    "error_rate": 0.0,
    "avg_latency_ms": 120.5,
    "min_latency_ms": 40.0,
    "max_latency_ms": 250.0,
    "median_latency_ms": 110.0,
    "p95_latency_ms": 200.0
  },
  "tokens": {
    "total": 1500,
    "prompt": 1000,
    "completion": 500
  },
  "browser": {
    "browser_version": "Chrome/148.0.7778.167",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.167 Safari/537.36",
    "window_width": 1280,
    "window_height": 1024,
    "window_x": 0,
    "window_y": 0,
    "viewport_width": 1279,
    "viewport_height": 936,
    "viewport_x1": 0,
    "viewport_y1": 88,
    "viewport_x2": 1279,
    "viewport_y2": 1024
  }
}

`client.list_sessions(limit=10, offset=0, status=None)`

List all your past and active browser sessions, sorted by creation date (newest first).

Returns (Dictionary):

python
{
  "success": True,
  "sessions": [
    {
      "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
      "is_active": True,
      "status": "idle",
      "created_at": "2026-05-01T12:00:00Z",
      "current_url": "https://example.com",
      "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "error_name": None,
      "error_message": None,
      "billing": { ... },
      "proxy_usage": { ... },
      "tokens": { ... },
      "browser": { ... }
    }
  ]
}

`client.get_session(session_id) -> BroSession`

Retrieve a BroSession instance for a specific existing session.

`client.stop_session(session_id)`

Gracefully shut down an active browser session. If you use the with block context manager, you do not need to call this manually.

`session.get_info()`

Retrieves the latest session information from the server and updates the session metadata (e.g. status, billing, stream_url).

`session.close()`

Gracefully shut down the active browser session. If you use the with block context manager, you do not need to call this manually. It is an alias for client.stop_session(...).

Session Management

client.create_session(enable_proxy=False, rotate_proxy=False, proxy_tier=None, proxy_policy=None, country=None, city=None, block_unproxied=False, cookies=None, session_timeout=None) -> BroSession

BroSession Properties

client.list_sessions(limit=10, offset=0, status=None)

client.get_session(session_id) -> BroSession

client.stop_session(session_id)

session.get_info()

session.close()