Launch Parameters

Launch parameters configure how browsers start and behave in your sessions. You can pass them as individual query parameters or as a single JSON launch parameter in the URL.

If you've used Puppeteer or Playwright, these are the cloud equivalent of browser.launch() options.

Passing Launch Options

There are two ways to pass options to the browser: as individual query parameters in the URL, or as a JSON object via the launch parameter.

Query parameters are passed directly in the URL (e.g., &proxy=residential&humanlike=true). Best for simple, standalone settings.
The launch object is a JSON string passed as a single launch query parameter, either URL-encoded or base64-encoded. Use it for browser-level options like headless and stealth, or array flags like args: [...] whose brackets, quotes, and commas require encoding.

Both methods can be used together. Browserless merges them, with individual query parameters taking precedence.

Query Parameters

These are passed directly in the URL, e.g. ?token=YOUR_TOKEN&proxy=residential.

Parameter	Description	Default
`token`	The authorization token for API access.	none
`timeout`	Maximum session duration in milliseconds. The session will automatically close after this time to prevent overuse. Defaults to 60000ms. Maximum value depends on your plan (see Session Limits).	60000
`proxy`	Routes browser traffic through a proxy. Only supports proxy=residential for Browserless's residential proxy pool. Omit to use the IP of the machine in the cloud running the container, meaning it's a fixed datacenter IP.	none
`proxyCountry`	Used with proxy=residential to specify the exit node's country. Accepts ISO 3166 country codes (e.g., us, gb, de). If omitted, a random location is chosen.	none
`proxyCity`	Used with proxy=residential to specify the exit node's city (e.g., chicago, london). Requires Scale plan (500k+ units).	none
`proxySticky`	Used with proxy=residential to maintain the same proxy IP across a session (when possible). Useful for sites that expect consistent IP usage.	`false`
`proxyLocaleMatch`	Used with proxy=residential to automatically configure browser locale settings to match the proxy location. Recommended when using proxyCountry to improve stealth by aligning browser language preferences with the geographic region.	`false`
`proxyPreset`	Website-specific proxy configuration. Use px_gov01 for government websites or px_ipv6 for Google domains (Maps, YouTube, etc.) to ensure optimal proxy vendor selection.	none
`externalProxyServer`	External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port. When set, routes requests through this proxy instead of built-in residential proxies. Credentials can be included directly in the URL.	none
`humanlike`	Simulates human-like behavior such as natural mouse movement, typing, and random delays. In the BQL IDE, this can be toggled in session settings. For direct BQL GraphQL calls, use humanlike: true in the launch payload. Recommended for strict bot detection scenarios.	`false`
`blockAds`	Enables the built-in ad blocker (powered by uBlock Origin). Helps speed up scripts and reduce noise by blocking ads and trackers. Especially useful for scraping to avoid popups and clutter. Note: may cause some sites to fail to load correctly.	`false`
`blockConsentModals`	Automatically blocks or dismisses cookie/GDPR consent banners. Available in BQL sessions and the /screenshot and /pdf REST APIs. In BQL, toggle it via the IDE or launch JSON. Useful for cleaner scraping by removing overlays.	`false`
`record`	Enables session recording functionality for debugging and monitoring purposes.	`false`
`replay`	Enables session recording for replay. When true, the session is recorded and can be replayed later.	`false`

The `launch` Object

Options in the launch object are passed as an encoded JSON string. This is the equivalent of Puppeteer's launch({ options }), passed as a query parameter to the cloud service. See the full list of options in the API reference.

Parameter	Description	Default
`args`	Array of Chrome command-line flags to pass at browser launch (e.g. ["--window-size=1280,720", "--lang=en-US"]). See the Chrome Flags section for available flags.	[]
`headless`	Runs the browser in headless mode. Set to false to enable headful mode (with a GUI). While the GUI isn't visible in cloud environments, headful mode may help bypass bot detection. Note: it uses more resources.	`true`
`stealth`	Enables stealth mode to reduce automation signals (similar to puppeteer-extra's stealth plugin). Set to true to enable stealth techniques.	`false`
`slowMo`	Adds delays between browser actions to slow down automation. Useful for debugging or bypassing rate limits. Value in milliseconds.	0
`ignoreDefaultArgs`	Controls which default Puppeteer/Playwright arguments to ignore when launching the browser. Can be a boolean or array of specific arguments to ignore.	`false`
`acceptInsecureCerts`	Accepts insecure certificates during navigation. Useful for testing sites with self-signed certificates or certificate issues.	`false`

Encoding the `launch` Value

The launch value must be encoded before being appended to the URL. You can use URL encoding or base64. Both work the same way. Base64 is simpler because it avoids manually escaping brackets, quotes, and commas.

URL encoding

JavaScript
Python
cURL

const launch = JSON.stringify({
  args: ["--window-size=1280,720"],
});

const url = `https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE&launch=${encodeURIComponent(launch)}`;

import json
import urllib.parse

launch = json.dumps({
    "args": ["--window-size=1280,720"],
})

url = f"https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE&launch={urllib.parse.quote(launch)}"

curl --request POST \
  --url 'https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE&launch=%7B%22args%22%3A%5B%22--window-size%3D1280%2C720%22%5D%7D' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation { goto(url: \"https://example.com\") { status } }"}'

Base64 encoding

JavaScript
Python
cURL

const launch = btoa(JSON.stringify({
  args: ["--window-size=1280,720"],
}));

const url = `https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE&launch=${launch}`;

import json
import base64

launch = base64.b64encode(json.dumps({
    "args": ["--window-size=1280,720"],
}).encode()).decode()

url = f"https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE&launch={launch}"

LAUNCH=$(echo -n '{"args":["--window-size=1280,720"]}' | base64)

curl --request POST \
  --url "https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE&launch=${LAUNCH}" \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation { goto(url: \"https://example.com\") { status } }"}'

Chrome Flags

Chrome flags are passed via the args array inside the launch object. Encode the value before use (see Encoding the launch Value above).

Before encoding:

{"args":["--window-size=1920,1080","--lang=en-US"]}

Encoded:

?launch=%7B%22args%22%3A%5B%22--window-size%3D1920%2C1080%22%2C%22--lang%3Den-US%22%5D%7D

Enterprise plans support the full set of Chrome command-line switches. The following flags are available to all accounts:

--disable-features
--disable-setuid-sandbox
--disable-site-isolation-trials
--disable-web-security
--enable-features
--font-render-hinting
--force-color-profile
--lang
--proxy-bypass-list
--proxy-server
--window-size

Next Steps

Where to go next:

Bot Detection

Learn how Browserless handles stealth, proxies, and CAPTCHA solving

Writing BQL Queries

Covers GraphQL mutations, aliases, and BQL syntax

Using the IDE

Use the query editor, run sessions live, and export code to your project

Passing Launch Options​

Query Parameters​

The launch Object​

Encoding the launch Value​

Chrome Flags​

Next Steps​