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

   JavaScript

   npm install puppeteer-core

   Python

   pip install pyppeteer

   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

   JavaScript

   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);

   Python

   import asyncio
   from pyppeteer import connect
   
   TOKEN = "YOUR_API_TOKEN_HERE"
   
   async def get_page_title():
       # Connect to Browserless using WebSocket endpoint
       browser = await connect({
           "browserWSEndpoint": f"wss://production-sfo.browserless.io/?token={TOKEN}"
       })
   
       page = await browser.newPage()
       await page.goto("https://www.example.com/")
   
       title = await page.title()
       print(f"The page's title is: {title}")
   
       await browser.close()
   
   if __name__ == "__main__":
       asyncio.run(get_page_title())

   Playwright

   JavaScript

   import { chromium } from "playwright-core";
   
   const TOKEN = "YOUR_API_TOKEN_HERE"; // Replace with your actual token
   
   async function takeScreenshot() {
     // 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/");
   
     // Take a screenshot and save it locally
     await page.screenshot({ path: "screenshot.png" });
     console.log("Screenshot saved as screenshot.png");
   
     // Clean up resources
     await browser.close();
   }
   
   takeScreenshot().catch(console.error);

   Python

   from playwright.sync_api import sync_playwright
   
   TOKEN = "YOUR_API_TOKEN_HERE"  # Replace with your actual token
   
   def take_screenshot():
       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/")
   
           # Take a screenshot and save it locally
           page.screenshot(path="screenshot.png")
           print("Screenshot saved as screenshot.png")
   
           # Clean up resources
           browser.close()
   
   if __name__ == "__main__":
       take_screenshot()

   Java

   package org.example;
   
   import com.microsoft.playwright.*;
   import java.nio.file.Paths;
   
   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/");
   
               // Take a screenshot and save it locally
               page.screenshot(new Page.ScreenshotOptions().setPath(Paths.get("screenshot.png")));
               System.out.println("Screenshot saved as screenshot.png");
   
               // Clean up resources
               browser.close();
           }
       }
   }

   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/");
   
               // Take a screenshot and save it locally
               await page.ScreenshotAsync(new PageScreenshotOptions { Path = "screenshot.png" });
               Console.WriteLine("Screenshot saved as screenshot.png");
   
               // Get page information
               var title = await page.TitleAsync();
               var heading = await page.TextContentAsync("h1");
   
               Console.WriteLine($"Title: {title}, Heading: {heading}");
   
               // Clean up resources
               await browser.CloseAsync();
           }
       }
   }

4. Expected Output

   After running your script, you should see:

   Puppeteer

   • Console output: "The page's title is: Example Domain"
   • Successful connection to Browserless
   • Clean browser session termination

   Playwright

   • A screenshot file named screenshot.png created in your current directory
   • Console output: "Screenshot saved as screenshot.png"
   • Successful connection to Browserless

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