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.
- 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
launchobject is a JSON string passed as a singlelaunchquery parameter, either URL-encoded or base64-encoded. Use it for browser-level options likeheadlessandstealth, or array flags likeargs: [...]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 |
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 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 |
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 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 |
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.
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.