Quick Start

Connect to Browserless using either Puppeteer or Playwright through Chrome's DevTools Protocol (CDP) using websockets. This is the primary and recommended way to connect to Browserless, as it provides a stable and reliable connection.

Follow these steps to get started with Browserless:

1. Get Your API Token

   • Go to the Browserless dashboard
   • Sign up or log in to your account
   • Copy your API token from the dashboard

   

2. Install Library

   Choose your preferred automation library and install it:

   Puppeteer

   npm install puppeteer-core

   Playwright

   JavaScript

   npm install playwright-core

   Python

   pip install playwright

   Java

   <dependency>
     <groupId>com.microsoft.playwright</groupId>
     <artifactId>playwright</artifactId>
     <version>1.40.0</version>
   </dependency>

   C#

   dotnet add package Microsoft.Playwright

3. Run Your First Example

   Here's a complete working example:

   Puppeteer

   import puppeteer from "puppeteer-core";
   
   const TOKEN = "YOUR_API_TOKEN_HERE"; // Replace with your actual token
   
   async function getPageTitle() {
     // Connect to Browserless using WebSocket endpoint
     const browser = await puppeteer.connect({
       browserWSEndpoint: `wss://production-sfo.browserless.io?token=${TOKEN}`,
     });
   
     const page = await browser.newPage();
   
     // Navigate to the target website
     await page.goto("https://www.example.com/");
   
     // Get the page title
     const title = await page.title();
     console.log(`The page's title is: ${title}`);
   
     // Clean up resources
     await browser.close();
   }
   
   getPageTitle().catch(console.error);

   Output

   The page's title is: Example Domain

   Playwright

   JavaScript

   import { chromium } from "playwright-core";
   
   const TOKEN = "YOUR_API_TOKEN_HERE"; // Replace with your actual token
   
   async function getPageTitle() {
     // Connect to Browserless using CDP (recommended method)
     const browser = await chromium.connectOverCDP(
       `wss://production-sfo.browserless.io?token=${TOKEN}`
     );
   
     const context = await browser.newContext();
     const page = await context.newPage();
   
     // Navigate to the target website
     await page.goto("https://www.example.com/");
   
     // Get the page title
     const title = await page.title();
     console.log(`The page's title is: ${title}`);
   
     // Clean up resources
     await browser.close();
   }
   
   getPageTitle().catch(console.error);

   Output

   The page's title is: Example Domain

   Python

   from playwright.sync_api import sync_playwright
   
   TOKEN = "YOUR_API_TOKEN_HERE"  # Replace with your actual token
   
   def get_page_title():
       with sync_playwright() as p:
           # Connect to Browserless using CDP (recommended method)
           browser = p.chromium.connect_over_cdp(
               f"wss://production-sfo.browserless.io?token={TOKEN}"
           )
   
           context = browser.new_context()
           page = context.new_page()
   
           # Navigate to the target website
           page.goto("https://www.example.com/")
   
           # Get the page title
           title = page.title()
           print(f"The page's title is: {title}")
   
           # Clean up resources
           browser.close()
   
   if __name__ == "__main__":
       get_page_title()

   Output

   The page's title is: Example Domain

   Java

   package org.example;
   
   import com.microsoft.playwright.*;
   
   public class Main {
       public static void main(String[] args) {
           try (Playwright playwright = Playwright.create()) {
               final String TOKEN = "YOUR_API_TOKEN_HERE"; // Replace with your actual token
   
               // Connect to Browserless using CDP (recommended method)
               Browser browser = playwright.chromium().connectOverCDP(
                   String.format("wss://production-sfo.browserless.io?token=%s", TOKEN)
               );
   
               BrowserContext context = browser.newContext();
               Page page = context.newPage();
   
               // Navigate to the target website
               page.navigate("https://www.example.com/");
   
               // Get the page title
               String title = page.title();
               System.out.println("The page's title is: " + title);
   
               // Clean up resources
               browser.close();
           }
       }
   }

   Output

   The page's title is: Example Domain

   C#

   using Microsoft.Playwright;
   
   namespace PlaywrightExample
   {
       class Program
       {
           private const string TOKEN = "YOUR_API_TOKEN_HERE"; // Replace with your actual token
   
           public static async Task Main(string[] args)
           {
               using var playwright = await Playwright.CreateAsync();
   
               // Connect to Browserless using CDP (recommended method)
               var browser = await playwright.Chromium.ConnectOverCDPAsync(
                   $"wss://production-sfo.browserless.io?token={TOKEN}"
               );
   
               var context = await browser.NewContextAsync();
               var page = await context.NewPageAsync();
   
               // Navigate to the target website
               await page.GotoAsync("https://www.example.com/");
   
               // Get the page title
               var title = await page.TitleAsync();
               Console.WriteLine($"The page's title is: {title}");
   
               // Clean up resources
               await browser.CloseAsync();
           }
       }
   }

   Output

   The page's title is: Example Domain

tip

The examples above connect to the US West region (production-sfo). Browserless is also available in Europe. See Regional Endpoints to choose the region closest to your target sites.

Next Steps

Explore these key features to enhance your browser automation:

Persistent Sessions

Create and manage long-running browser sessions for complex automation workflows

Site Unblocking

Use advanced techniques to bypass anti-bot measures and unblock sites

Proxy Configuration

Configure both built-in residential proxies and third-party proxies

Frequently Asked Questions

How do I connect Puppeteer to Browserless?

Replace your local browser launch with a WebSocket connection to Browserless. Use puppeteer.connect() with the Browserless WebSocket URL and your API token as a query parameter.

Does Browserless support Playwright?

Yes. Connect Playwright to Browserless using browserType.connect() with the Browserless WebSocket URL. Both Chromium and Firefox browsers are supported for Playwright connections.

Do I need to change my existing automation code?

Minimal changes are needed. Replace your browser launch call with a connect call pointing to Browserless. The rest of your Puppeteer or Playwright code runs unchanged against the remote browser.

Is there a free tier to try Browserless?

Yes. Sign up at browserless.io for a free account that includes a limited number of browser sessions per month. This lets you test your automation code against managed browsers before scaling up.