Launch Parameters and Options

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. Whether you're using BQL, BaaS v2, or REST, these options let you tweak the browser environment to fit your needs.

Passing Launch Options

Two ways to specify launch options:

1. Individual Query Parameters: Add options directly to URLs (e.g., &headless=false, &proxy=residential). Best for simple boolean options.

2. Combined launch Parameter (JSON): For complex configurations, 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. It's essentially the equivalent of Puppeteer's launch({ options }) but provided to the cloud service:

   &launch={"headless":false,"stealth":true,"args":["--window-size=1920,1080"]}

   (URL-encoded) would configure a headful, stealth-enabled browser with a specific window size.

note

Browserless merges both methods if used together, with individual parameters taking precedence.

Launch Options (Query Parameters)

Below is a comprehensive list of available launch options you can use in query strings for Browserless REST APIs, for the exhaustive list refer to the launch options section in the API reference.

Parameter	Description	Default
launch	Launch options, which contains Browserless-specific options and Chrome flags inside the args array. You can provide this as a base-64 JSON.	{}
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.	60000
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). In BQL, stealth is always on by design and controlled via the humanlike option. In BaaS/REST, set to true to enable stealth techniques.	false (for BaaS/REST)
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
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
record	Enables session recording functionality for debugging and monitoring purposes.	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.	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
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
ignoreHTTPSErrors	Ignores HTTPS certificate errors during navigation. Useful for testing sites with self-signed certificates or certificate issues.	false

Example

The examples below demonstrate how to use launch parameters with the /pdf API in multiple programming languages. These same parameter patterns can be applied to all Browserless REST APIs (/content, /screenshot, /scrape, etc.) and adapted to other programming languages similarly.

In this example we will try to Control whether the browser runs with or without a graphical interface (aka headless mode):

cURL

# Generate PDF in headless mode (faster, no GUI)
curl -X POST \
"https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE&headless=true" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
  "url": "https://example.com",
  "options": {
    "format": "A4",
    "printBackground": true
  }
}' \
-o output.pdf

Javascript

import fs from 'fs/promises';

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/pdf?token=${TOKEN}&headless=true`;

const headers = {
  "Cache-Control": "no-cache",
  "Content-Type": "application/json"
};

const data = {
  url: "https://example.com",
  options: {
    format: "A4",
    printBackground: true,
    margin: {
      top: "1cm",
      bottom: "1cm",
      left: "1cm",
      right: "1cm"
    }
  }
};

const generatePDF = async () => {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(data)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const pdfBuffer = await response.arrayBuffer();
    await fs.writeFile("output.pdf", Buffer.from(pdfBuffer));
    console.log("PDF saved as output.pdf");
  } catch (error) {
    console.error("Error generating PDF:", error.message);
  }
};

generatePDF();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/pdf?token={TOKEN}&headless=true"

headers = {
    "Cache-Control": "no-cache",
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com",
    "options": {
        "format": "A4",
        "printBackground": True,
        "margin": {
            "top": "1cm",
            "bottom": "1cm",
            "left": "1cm",
            "right": "1cm"
        }
    }
}

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()  # Raises an HTTPError for bad responses
    
    with open("output.pdf", "wb") as file:
        file.write(response.content)
    
    print("PDF saved as output.pdf")
except requests.exceptions.RequestException as e:
    print(f"Error generating PDF: {e}")

Java

import java.io.*;
import java.net.URI;
import java.net.http.*;
import java.nio.file.*;

public class GeneratePDF {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/pdf?token=" + TOKEN + "&headless=true";

        String jsonData = """
        {
            "url": "https://example.com",
            "options": {
                "format": "A4",
                "printBackground": true,
                "margin": {
                    "top": "1cm",
                    "bottom": "1cm",
                    "left": "1cm",
                    "right": "1cm"
                }
            }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Cache-Control", "no-cache")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<InputStream> response = client.send(request, HttpResponse.BodyHandlers.ofInputStream());
            
            if (response.statusCode() == 200) {
                Files.copy(response.body(), Paths.get("output.pdf"), StandardCopyOption.REPLACE_EXISTING);
                System.out.println("PDF saved as output.pdf");
            } else {
                System.err.println("Error: HTTP " + response.statusCode());
            }
        } catch (Exception e) {
            System.err.println("Error generating PDF: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/pdf?token={TOKEN}&headless=true";

        string jsonData = @"
        {
            ""url"": ""https://example.com"",
            ""options"": {
                ""format"": ""A4"",
                ""printBackground"": true,
                ""margin"": {
                    ""top"": ""1cm"",
                    ""bottom"": ""1cm"",
                    ""left"": ""1cm"",
                    ""right"": ""1cm""
                }
            }
        }";

        using var client = new HttpClient();

        var request = new HttpRequestMessage(HttpMethod.Post, url)
        {
            Content = new StringContent(jsonData, Encoding.UTF8, "application/json")
        };

        request.Headers.Add("Cache-Control", "no-cache");

        try
        {
            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            
            var pdfBytes = await response.Content.ReadAsByteArrayAsync();
            await File.WriteAllBytesAsync("output.pdf", pdfBytes);
            Console.WriteLine("PDF saved as output.pdf");
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"HTTP Error: {ex.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}