Browserless

Headless Chrome browser as a service. Take screenshots, generate PDFs, scrape JS-rendered pages, and run Puppeteer/Playwright scripts without managing browser infrastructure.

Official docs: https://docs.browserless.io/

---

When to Use

Use this skill when you need to:

• Scrape JavaScript-heavy pages (React, Vue, Angular)
• Take full-page or element screenshots
• Generate PDFs from web pages
• Execute custom JavaScript in a browser context
• Bypass bot detection with stealth mode
• Run Puppeteer/Playwright scripts in the cloud

---

Prerequisites

1. Create an account at https://www.browserless.io/
2. Get your API token from https://account.browserless.io/

Set environment variable:

export BROWSERLESS_API_TOKEN="your-api-token-here"

---

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

1. Scrape Data (CSS Selectors)

Extract structured JSON using CSS selectors:

bash -c 'curl -s -X POST "https://production-sfo.browserless.io/scrape?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '"'"'{
  "url": "https://example.com",
  "elements": [
  {"selector": "h1"},
  {"selector": "p"}
  ]
  }'"'"' | jq .'

With wait options:

bash -c 'curl -s -X POST "https://production-sfo.browserless.io/scrape?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '"'"'{
  "url": "https://news.ycombinator.com",
  "elements": [{"selector": ".titleline > a"}],
  "gotoOptions": {
  "waitUntil": "networkidle2",
  "timeout": 30000
  }
  }'"'"' | jq '"'"'.data[0].results[:3]'"'"''

2. Take Screenshots

Full page screenshot:

curl -s -X POST "https://production-sfo.browserless.io/screenshot?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '{
  "url": "https://example.com",
  "options": {
  "fullPage": true,
  "type": "png"
  }
  }' --output screenshot.png

Element screenshot:

curl -s -X POST "https://production-sfo.browserless.io/screenshot?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '{
  "url": "https://example.com",
  "options": {
  "type": "png"
  },
  "selector": "h1"
  }' --output element.png

With viewport size:

curl -s -X POST "https://production-sfo.browserless.io/screenshot?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '{
  "url": "https://example.com",
  "viewport": {
  "width": 1920,
  "height": 1080
  },
  "options": {
  "type": "jpeg",
  "quality": 80
  }
  }' --output screenshot.jpg

3. Generate PDF

curl -s -X POST "https://production-sfo.browserless.io/pdf?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '{
  "url": "https://example.com",
  "options": {
  "format": "A4",
  "printBackground": true,
  "margin": {
  "top": "1cm",
  "bottom": "1cm"
  }
  }
  }' --output page.pdf

4. Get Rendered HTML

Get fully rendered HTML after JavaScript execution:

curl -s -X POST "https://production-sfo.browserless.io/content?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '{
  "url": "https://example.com",
  "gotoOptions": {
  "waitUntil": "networkidle0"
  }
  }'

5. Execute Custom JavaScript (Click, Type, etc.)

Run Puppeteer code with full interaction support:

Click element:

curl -s -X POST "https://production-sfo.browserless.io/function?token=${BROWSERLESS_API_TOKEN}" -H "Content-Type: application/javascript" -d 'export default async ({ page }) => {
  await page.goto("https://example.com");
  await page.click("a");
  return { data: { url: page.url() }, type: "application/json" };
  }' | jq .

Type into input:

curl -s -X POST "https://production-sfo.browserless.io/function?token=${BROWSERLESS_API_TOKEN}" -H "Content-Type: application/javascript" -d 'export default async ({ page }) => {
  await page.goto("https://duckduckgo.com");
  await page.waitForSelector("input[name=q]");
  await page.type("input[name=q]", "hello world");
  const val = await page.$eval("input[name=q]", e => e.value);
  return { data: { typed: val }, type: "application/json" };
  }' | jq .

Form submission:

curl -s -X POST "https://production-sfo.browserless.io/function?token=${BROWSERLESS_API_TOKEN}" -H "Content-Type: application/javascript" -d 'export default async ({ page }) => {
  await page.goto("https://duckduckgo.com");
  await page.type("input[name=q]", "test query");
  await page.keyboard.press("Enter");
  await page.waitForNavigation();
  return { data: { title: await page.title() }, type: "application/json" };
  }' | jq .

Extract data with custom script:

curl -s -X POST "https://production-sfo.browserless.io/function?token=${BROWSERLESS_API_TOKEN}" -H "Content-Type: application/javascript" -d 'export default async ({ page }) => {
  await page.goto("https://news.ycombinator.com");
  const links = await page.$$eval(".titleline > a", els => els.slice(0,5).map(a => ({title: a.innerText, url: a.href})));
  return { data: links, type: "application/json" };
  }' | jq .

6. Unblock Protected Sites

Bypass bot detection:

bash -c 'curl -s -X POST "https://production-sfo.browserless.io/unblock?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '"'"'{
  "url": "https://example.com",
  "browserWSEndpoint": false,
  "cookies": false,
  "content": true,
  "screenshot": false
  }'"'"' | jq .'

7. Download Files

Trigger and capture file downloads:

curl -s -X POST "https://production-sfo.browserless.io/download?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '{
  "url": "https://example.com/file.pdf"
  }' --output downloaded.pdf

8. Stealth Mode

Enable stealth mode to avoid detection:

bash -c 'curl -s -X POST "https://production-sfo.browserless.io/scrape?token=${BROWSERLESS_API_TOKEN}&stealth=true" --header "Content-Type: application/json" -d '"'"'{
  "url": "https://example.com",
  "elements": [{"selector": "body"}]
  }'"'"' | jq .'

9. Export Page with Resources

Fetch a URL and get content in native format. Can bundle all resources (CSS, JS, images) as zip:

Basic export:

curl -s -X POST "https://production-sfo.browserless.io/export?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '{
  "url": "https://example.com"
  }' --output page.html

Export with all resources as ZIP:

curl -s -X POST "https://production-sfo.browserless.io/export?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '{
  "url": "https://example.com",
  "includeResources": true
  }' --output webpage.zip

10. Performance Audit (Lighthouse)

Run Lighthouse audits for accessibility, performance, SEO, best practices:

Full audit:

bash -c 'curl -s -X POST "https://production-sfo.browserless.io/performance?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '"'"'{
  "url": "https://example.com"
  }'"'"' | jq '"'"'.data.categories | to_entries[] | {category: .key, score: .value.score}'"'"''

Specific category (accessibility, performance, seo, best-practices, pwa):

bash -c 'curl -s -X POST "https://production-sfo.browserless.io/performance?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '"'"'{
  "url": "https://example.com",
  "config": {
  "extends": "lighthouse:default",
  "settings": {
  "onlyCategories": ["performance"]
  }
  }
  }'"'"' | jq '"'"'.data.audits | to_entries[:5][] | {audit: .key, score: .value.score, display: .value.displayValue}'"'"''

Specific audit (e.g., unminified-css, first-contentful-paint):

bash -c 'curl -s -X POST "https://production-sfo.browserless.io/performance?token=${BROWSERLESS_API_TOKEN}" --header "Content-Type: application/json" -d '"'"'{
  "url": "https://example.com",
  "config": {
  "extends": "lighthouse:default",
  "settings": {
  "onlyAudits": ["first-contentful-paint", "largest-contentful-paint"]
  }
  }
  }'"'"' | jq '"'"'.data.audits'"'"''

---

API Endpoints

Endpoint	Method	Description
/scrape	POST	Extract data with CSS selectors
/screenshot	POST	Capture screenshots (PNG/JPEG)
/pdf	POST	Generate PDF documents
/content	POST	Get rendered HTML
/function	POST	Execute custom Puppeteer code
/unblock	POST	Bypass bot protection
/download	POST	Download files
/export	POST	Export page with resources as ZIP
/performance	POST	Lighthouse audits (a11y, perf, SEO)

---

Common Options

gotoOptions

Control page navigation:

{
  "gotoOptions": {
  "waitUntil": "networkidle2",
  "timeout": 30000
  }
}

waitUntil values:

• load - Wait for load event
• domcontentloaded - Wait for DOMContentLoaded
• networkidle0 - No network connections for 500ms
• networkidle2 - Max 2 network connections for 500ms

waitFor Options

{
  "waitForTimeout": 1000,
  "waitForSelector": {"selector": ".loaded", "timeout": 5000},
  "waitForFunction": {"fn": "() => document.ready", "timeout": 5000}
}

Viewport

{
  "viewport": {
  "width": 1920,
  "height": 1080,
  "deviceScaleFactor": 2
  }
}

---

Query Parameters

Parameter	Description
token	API token (required)
stealth	Enable stealth mode (true/false)
blockAds	Block advertisements
proxy	Use proxy server

---

Response Format

Scrape response:

{
  "data": [
  {
  "selector": "h1",
  "results": [
  {
  "text": "Example Domain",
  "html": "Example Domain",
  "attributes": [{"name": "class", "value": "title"}],
  "width": 400,
  "height": 50,
  "top": 100,
  "left": 50
  }
  ]
  }
  ]
}

---

Guidelines

1. waitUntil: Use networkidle2 for most pages, networkidle0 for SPAs
2. Timeouts: Default is 30s; increase for slow pages
3. Stealth Mode: Enable for sites with bot detection
4. Screenshots: Use jpeg with quality 80 for smaller files
5. Rate Limits: Check your plan limits at https://account.browserless.io/
6. Regions: Use region-specific endpoints for better latency:

• production-sfo.browserless.io (US West)
• production-lon.browserless.io (Europe)