Screenshot API

Capture PNG, JPEG, or WebP screenshots of a page. Pass Puppeteer-style settings through the options object.

Endpoint

• Method: POST
• Path: /screenshot
• Auth: token query parameter (?token=)
• Content-Type: application/json
• Response: image/png (or image/jpeg, image/webp based on options.type)

See the OpenAPI reference for complete details.

Quickstart

cURL

curl -X POST \
  "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "options": {
    "fullPage": true,
    "type": "png"
  }
}' \
  --output "screenshot.png"

Javascript

import fs from 'fs/promises';

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/screenshot?token=${TOKEN}`;
const headers = {
  "Cache-Control": "no-cache",
  "Content-Type": "application/json"
};

const data = {
  url: "https://example.com/",
  options: {
    fullPage: true,
    type: "png"
  }
};

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

  const imageBuffer = await response.arrayBuffer();
  await fs.writeFile("screenshot.png", Buffer.from(imageBuffer));
  console.log("Screenshot saved as screenshot.png");
};

takeScreenshot();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/screenshot?token={TOKEN}"
headers = {
    "Cache-Control": "no-cache",
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com/",
    "options": {
        "fullPage": True,
        "type": "png"
    }
}

response = requests.post(url, headers=headers, json=data)

with open("screenshot.png", "wb") as file:
    file.write(response.content)

print("Screenshot saved as screenshot.png")

Response

HTTP/1.1 200 OK
Content-Type: image/png

<binary>

Examples

Setting HTML content

Use html to render inline content instead of navigating to a URL. When you send html, do not include url in the same request. Browserless doesn't allow setting options.path for the /screenshot API.

curl -X POST \
  "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "options": {
    "type": "webp",
    "omitBackground": true
  }
}' \
  --output "screenshot.webp"

Adding custom styles and scripts

Use addScriptTag and addStyleTag to inject scripts and styles before the screenshot is taken.

curl -X POST \
  "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "addScriptTag": [
    { "url": "https://code.jquery.com/jquery-3.7.1.min.js" },
    { "content": "document.querySelector(`h1`).innerText = `Hello Word!`" }
  ],
  "addStyleTag": [
    {
      "content": "body { height: 100vh; background: linear-gradient(45deg, #da5a44, #a32784); }"
    },
    {
      "url": "https://interactive-examples.mdn.mozilla.net/live-examples/css-examples/text-decoration/text-decoration-color.css"
    }
  ]
}' \
  --output "screenshot.png"

Bot detection troubleshooting

If screenshots return blank images, CAPTCHA pages, or content that differs from what a real browser would show, the site is likely blocking automation. Signs include:

• Blank or white screenshots
• CAPTCHA challenge pages captured instead of actual content
• Access denied or 403 error pages in the screenshot
• Missing or broken page elements compared to a regular browser

The /unblock API is specifically designed to bypass bot detection mechanisms like Datadome and passive CAPTCHAs. It can return a screenshot directly when screenshot: true is set, delivering a base64-encoded PNG of the page after anti-bot measures have been bypassed. For best results, combine it with residential proxies.

Configuration options

The /screenshot API supports shared request configuration options that apply across REST endpoints:

• Waiting for things: Wait for events, functions, selectors, or timeouts before capturing the screenshot
• Navigation options: Customize navigation behavior with gotoOptions
• Rejecting undesired requests: Block resources with rejectResourceTypes and rejectRequestPattern
• Continue on error: Use bestAttempt to continue when async events fail or time out