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.

Prerequisites

A Browserless API token from your account dashboard
Familiarity with BQL language basics

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 built-in proxy. Set proxy=residential for the residential pool (6 units/MB) or proxy=datacenter for the cheaper datacenter pool (2 units/MB). Omit to use the host machine's own IP.	none
`proxyCountry`	Used with the built-in proxy 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 the built-in proxy to specify the exit node's city (e.g., chicago, london). Requires Scale plan (500k+ units).	none
`proxyState`	Used with the built-in proxy to specify the exit node's state or province within proxyCountry (e.g., california). Requires Scale plan (500k+ units). See the BrowserQL proxies page for the value format.	none
`proxySticky`	Used with the built-in proxy to maintain the same proxy IP across a session (when possible). Useful for sites that expect consistent IP usage.	`false`
`proxyLocaleMatch`	Used with the built-in proxy 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 preset for the residential network. 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 the built-in proxy. 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 calls, pass it as a URL query parameter, e.g. &humanlike=true. Recommended for strict bot detection scenarios.	`false`
`emulationOs`	Presents the session as another operating system: windows, macos, linux, or android. Applies that platform's full fingerprint stack (User-Agent, client hints, navigator.platform, GPU, fonts). Values are exact-match lowercase; anything else is ignored. Omit to keep the native Linux identity.	none
`emulatedDevice`	Android device slug for emulationOs=android (e.g., pixel-8-pro, galaxy-s25-ultra). Omit to have a device picked for you. Sending it without emulationOs=android returns a 400.	none
`screen`	Desktop screen resolution as WIDTHxHEIGHT (e.g., 1920x1080) for a desktop emulationOs. Sets the reported screen size and window size. Omit to have one picked per session. Ignored for emulationOs=android.	none
`deviceScaleFactor`	Device pixel ratio for the desktop screen: 1 or 1.25. Omit to use the default for the session's identity. Ignored for emulationOs=android.	none
`deviceSlot`	Pins the session to one of your identity's stable device slots (0-based; 8 slots by default). Each slot keeps the same GPU, screen, cores, memory, and OS version across sessions, so traffic spreads across several consistent machines. Requires a desktop emulationOs.	none
`integrationId`	Connects a 1Password service account to the session so it can fill credentials from your vault without exposing them to your code.	none
`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`
`blockAdsInclude`	With blockAds=true, loads only the named uBlock Origin rulesets (comma-separated list or JSON array of ruleset ids) instead of all of them, lowering per-launch startup cost under load. Opt-in: omit it and blockAds loads the full extension, unchanged. See the BrowserQL launch parameters page for the recommended set and full ruleset list.	none
`blockConsentModals`	Automatically blocks or dismisses cookie/GDPR consent banners. Available in BQL sessions and the /screenshot and /pdf REST APIs. In BQL, toggle it in the IDE or pass it as a URL query parameter, e.g. &blockConsentModals=true. 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`
`profile`	Loads a previously saved authentication profile (cookies, localStorage, IndexedDB) into the session before your code runs. The profile must already exist for this token; create one via POST /profile.	none

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

Restricting ad-block rulesets (`blockAdsInclude`)

When you pass blockAds=true, Browserless loads uBlock Origin Lite and compiles all 57 filter rulesets (~69,000 rules) on every fresh browser launch — a CPU-bound cost that adds up when many browsers start at once.

blockAdsInclude lets a request load only the rulesets it needs, so Chrome compiles fewer of them and the browser starts faster.

It is opt-in: if you don't pass it, blockAds=true behaves exactly as before — the full extension with all 57 rulesets.

# no blockAdsInclude — full extension, unchanged
?blockAds=true

# only the recommended core lists — faster launch
?blockAds=true&blockAdsInclude=ublock-filters,easylist,easyprivacy,pgl,ublock-badware,urlhaus-full

Applies only when blockAds=true.
Value is a comma-separated list or a JSON array of ruleset ids.
Unknown ids are rejected with 400 Bad Request.

note

blockAdsInclude is currently honored on the BrowserQL endpoints (/chromium/bql, /chrome/bql, /stealth/bql), the CDP WebSocket connection, and the /unblock, /screenshot, and /pdf REST endpoints. Persistent /session connections and endpoints that use the bundled open-source uBlock build still load the full ruleset set. Where it isn't honored, blockAds=true continues to work with the full extension.

Recommended set

These 6 language-neutral lists cover general ads, trackers, and malware — enough for typical traffic. Pass them for a faster launch:

blockAdsInclude=ublock-filters,easylist,easyprivacy,pgl,ublock-badware,urlhaus-full

What each group blocks

Group	What it blocks	When to include
Recommended (6)	general ads, third-party trackers, malicious/badware URLs (language-neutral)	almost always — the recommended set
Locale (37)	region/language-specific ad lists (e.g. German, Japanese)	only if you scrape sites in that language
Optional (14)	cookie-consent banners, overlays, social/chat/AI widgets, notifications, experimental	only if you want annoyance removal

Full ruleset reference

Include only the locales your traffic actually targets — the locale lists are the bulk of the rules and therefore most of the startup cost. (This list reflects the bundled uBlock Origin Lite build and can change when the extension is updated.)

Recommended (6) — the core set.

id	list
`ublock-filters`	uBlock filters – Ads, trackers, and more
`easylist`	EasyList
`easyprivacy`	EasyPrivacy
`pgl`	Peter Lowe – Ads, trackers, and more
`ublock-badware`	uBlock filters – Badware risks
`urlhaus-full`	Malicious URL Blocklist

Optional (14) — opt-in (annoyances, mobile, experimental)

id	list
`adguard-mobile`	AdGuard/uBO – Mobile Ads
`block-lan`	Block Outsider Intrusion into LAN
`dpollock-0`	Dan Pollock's hosts file
`adguard-spyware-url`	AdGuard/uBO – URL Tracking Protection
`annoyances-ai`	EasyList – AI Widgets
`annoyances-cookies`	EasyList/uBO – Cookie Notices
`annoyances-overlays`	EasyList/uBO – Overlay Notices
`annoyances-social`	EasyList – Social Widgets
`annoyances-widgets`	EasyList – Chat Widgets
`annoyances-others`	EasyList – Other Annoyances
`annoyances-notifications`	EasyList – Notifications
`ublock-experimental`	uBlock filters – Experimental
`ubol-tests`	uBO Lite Test Filters
`rus-1`	RU AdList: Counters

Locale (37) — region/language-specific ad lists

id	list	languages
`alb-0`	Adblock List for Albania	sq
`ara-0`	Liste AR	ar kab
`bgr-0`	Bulgarian Adblock list	bg mk
`chn-0`	AdGuard Chinese	ug zh
`cze-0`	EasyList Czech and Slovak	cs sk
`deu-0`	EasyList Germany	de dsb hsb lb rm
`est-0`	Eesti saitidele kohandatud filter	et
`fin-0`	Adblock List for Finland	fi
`fra-0`	AdGuard Français	ar br ff fr lb oc son
`grc-0`	Greek AdBlock Filter	el
`hrv-0`	Serbo-Croatian filters	bs hr sr
`hun-0`	hufilter	hu
`idn-0`	ABPindo	id ms
`ind-0`	IndianList	as bn gu hi kn ml mr ne pa si ta te
`irn-0`	PersianBlocker	fa ps tg
`isl-0`	Icelandic ABP List	is
`isr-0`	EasyList Hebrew	he
`ita-0`	EasyList Italy	it lij
`jpn-1`	AdGuard Japanese	ja
`kor-1`	List-KR Classic	ko
`ltu-0`	EasyList Lithuania	lt
`lva-0`	Latvian List	lv
`mkd-0`	Macedonian adBlock Filters	mk
`nld-0`	AdGuard Dutch	af fy nl
`nor-0`	Nordiske filtre	nb nn no da is
`pol-0`	Oficjalne Polskie Filtry	szl pl
`pol-3`	CERT.PL's Warning List	szl pl
`rou-1`	Romanian Ad (ROad) Block List Light	ro md
`rus-0`	RU AdList	be kk tt ru uz
`spa-0`	EasyList Spanish	es ca eu gl …
`spa-1`	AdGuard Spanish/Portuguese	es pt ca …
`svn-0`	Slovenian List	sl
`swe-1`	Frellwit's Swedish Filter	sv
`tha-0`	EasyList Thailand	th
`tur-0`	AdGuard Turkish	tr
`ukr-0`	AdGuard Ukrainian	uk
`vie-1`	ABPVN List	vi

FAQ & Troubleshooting

Why am I getting a 403 Forbidden response?

Your API token is missing or malformed. Pass it as a ?token= query parameter. Check your account dashboard to verify the token is active.

My query times out before completing

Increase the timeout parameter on your mutation or use a more specific waitUntil condition. Long-running pages may need networkIdle instead of load.

Why does ttl or profile_id on my BQL URL do nothing?

Use timeout to set how long the BQL session runs, and profile (not profile_id) to load a saved profile. On the cloud, query parameters Browserless doesn't recognize are dropped without an error, so a misspelled or unsupported parameter fails silently. ttl belongs to the persistent Session API request body, not to BQL URLs.

Do humanlike and blockConsentModals go in the launch JSON?

No. Pass them as URL query parameters, for example &humanlike=true&blockConsentModals=true. BQL reads both from the query string only.

Next steps

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

Was this page helpful?

Passing Launch Options​

Query Parameters​

The launch Object​

Encoding the launch Value​

Chrome Flags​

Restricting ad-block rulesets (blockAdsInclude)​

Recommended set​

What each group blocks​

Full ruleset reference​

FAQ & Troubleshooting​

Next steps​