Launch Parameters

Browserless allows extensive configuration of how browsers are launched and behave during your sessions. These launch parameters can be provided either via query parameters in the URL or through a special JSON launch payload. This section covers all the available launch options, their purpose, and default values. Whether you're using BrowserQL, BaaS v2, or REST APIs, these options let you tweak the browser environment to fit your needs.

Passing Launch Options

There are two ways to specify launch options on Browserless v2:

Individual Query Parameters: Many common options can be set by adding a query parameter to your connection URL or API call. For example, &headless=false to run in headful mode, &proxy=residential to use the built-in residential proxies, etc. This is straightforward for boolean or simple options.
Combined launch Parameter (JSON): For complex configurations, you can use a single query param launch with a JSON string as its value. This JSON can include any Chrome flags or Browserless-specific settings in a structured way. This approach is useful when you need to set multiple flags at once or use non-boolean values. It's essentially the equivalent of Puppeteer's launch({ options }) but provided to the cloud service. For example:
```
&launch={"headless":false,"stealth":true,"args":["--window-size=1920,1080"]}
```
(URL-encoded) would configure a headful, stealth-enabled browser with a specific window size.

Both methods achieve the same result. Under the hood, Browserless will merge any individual query params with the JSON launch config if both are provided (individual params typically override the JSON fields if there's overlap). For simplicity, if you only need to toggle a few settings, use query params; if you have many settings, use the single launch param.

Common Launch Options

Below is a list of common launch options you can use in query strings. Unless stated otherwise, these can be used in BaaS v2 (library connections) and REST API calls alike. BrowserQL internally uses some of these, but BQL users typically set these via the IDE session settings rather than manually in a URL.

Parameter	Description	Default	BrowserQL	BaaS v2	REST APIs
`headless`	Run browser in headless mode. Set to `false` to launch the browser in "headful" mode (with a GUI). In cloud environments you won't actually see a GUI, but headful mode can sometimes bypass bot detection (since some bots detect headless). Using `headless=false` will consume more resources.	`true`	✅	✅	✅
`stealth`	Enable stealth plugin/mode for the browser. If `true`, Browserless will apply stealth techniques to the browser (like puppeteer-extra's stealth plugin) to remove obvious automation signals. In BrowserQL, stealth is generally always on by design (hence no toggle in BQL except through humanlike). In BaaS, you might use `stealth=true` when you need some bot evasion but are not using BQL.	`false` (for BaaS/REST)	✅	✅	✅
`humanlike`	Enable Human-like behavior – simulation of human input patterns (mouse movements, random small delays, realistic typing). In the BQL IDE, this is a session setting toggle. If you're making a BQL GraphQL call directly, you could include `humanlike: true` in the launch JSON. This option is not applicable to the REST or standard BaaS v2 endpoints, as it's a feature tightly integrated with BQL's operation. Use this when dealing with the strictest bot detections that look for non-human interaction patterns.	`false`	✅	❌	❌
`blockAds`	Enable the built-in ad blocker. Browserless uses uBlock Origin under the hood for ad-blocking. Setting `blockAds=true` will prevent a lot of ads and trackers from loading, which can speed up your script and reduce noise. This is useful for scraping because it declutters pages and avoids random ad popups.	`false`	✅	✅	✅
`blockConsentModals`	If `true`, Browserless will attempt to auto-block or auto-dismiss those cookie/GDPR consent banners on websites. This feature is currently available in BQL sessions. If you're using BQL, you can toggle it in the IDE or via launch JSON (`"blockConsentModals": true`). This helps streamline scraping by removing extra overlays.	`false`	✅	❌	❌
`proxy`	Use a proxy server for outgoing network requests. Options: - `proxy=residential`: Route traffic through Browserless's built-in residential proxy pool. This is a premium feature that uses real consumer ISP IPs, very useful for avoiding bot detection. If you use this, also set `proxyCountry` if you need a specific geolocation. - `proxy=<Your proxy URL>`: Provide your own proxy address. For example, `&proxy=http://user:pass@myproxy:port` for an HTTP proxy. Browserless will configure the browser to use that proxy. Make sure to URL-encode if your URL has special chars. - omit or blank: By default, if not set, no proxy is used (direct connection).	none	✅	✅	✅
`proxyCountry`	Works in conjunction with `proxy=residential`. Allows you to specify the country for the residential exit node. Use an ISO 3166 country code (e.g. `us`, `gb`, `de`, etc.). If not specified, Browserless will choose an IP of unspecified location.	none	✅	✅	✅
`proxySticky`	Works with `proxy=residential`. If `true`, requests will use the same proxy IP (when possible) throughout a session. This is useful when a site expects all requests to come from the same IP.	`false`	✅	✅	✅
`timeout`	Sets the maximum duration (in milliseconds) for the browser session before it's automatically closed. This helps prevent runaway sessions.	`60000`	✅	✅	✅

BrowserQL Specific Options

BrowserQL has some additional options that are specific to its behavior and are set through the session settings panel in the IDE:

Human-like Behavior: Simulates realistic user interactions with random delays and mouse movements.
Block Consent Modals: Automatically handles cookie consent prompts on websites.
Force Locale: Forces a specific browser locale (language and regional settings).
Residential Proxy: Routes requests through residential IPs for enhanced anonymity. Learn more in our Proxies guide.

BaaS v2 Advanced Options

For BaaS v2, you can use the launch parameter to pass a JSON object with advanced Chrome flags and Puppeteer options. Learn more in our Launch Options guide:

Puppeteer
Playwright

const launchArgs = {
  headless: false,
  stealth: true,
  args: ['--window-size=1920,1080', '--force-color-profile=srgb']
};

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN&launch=${JSON.stringify(launchArgs)}`,
});

const launchArgs = {
  headless: false,
  stealth: true,
  args: ['--window-size=1920,1080', '--force-color-profile=srgb']
};

const browser = await playwright.chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN&launch=${JSON.stringify(launchArgs)}`
);

REST API Options

When using REST APIs, you can include launch parameters in the URL query string or in the JSON body of your request:

// In URL query string
fetch("https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN&blockAds=true&stealth=true")

// In JSON body
fetch("https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com",
    options: { format: "A4" },
    launch: { stealth: true, blockAds: true }
  })
})

For a comprehensive list of Chrome flags and browserless-specific options, please refer to our Launch Options documentation.

Passing Launch Options​

Common Launch Options​

BrowserQL Specific Options​

BaaS v2 Advanced Options​

REST API Options​

Passing Launch Options

Common Launch Options

BrowserQL Specific Options

BaaS v2 Advanced Options

REST API Options