Taking Screenshots

info

Currently, Browserless V2 is available in production via two domains: production-sfo.browserless.io and production-lon.browserless.io

The screenshot API allows for simple navigation to a site and capturing a screenshot. browserless will respond with either a binary or base64 encode of a png or jpg (depending on parameters). This API exposes most of puppeteer's screenshot API through the posted JSON payload.

You can check the full Open API schema here.

Bot detection

If the /screenshot API is getting blocked by bot detectors, then we would recommend trying BrowserQL.

On this collection we'll look at:

• Basic Usage
• Setting HTML content
• Adding custom styles and scripts
• Rejecting Undesired Requests
• Navigation Options
• Continue on Error
• Waiting for Things

Basic Usage

BQL (Stealth)

If the /screenshot API is getting blocked by bot detectors, then we would recommend trying BrowserQL.

BQL Query

mutation Screenshot {
  goto(url: "https://example.com") {
    status
  }

  screenshot(omitBackground:true) {
    base64
  }
}

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation Screenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(omitBackground:true) {\n    base64\n  }\n}","variables":"","operationName":"Screenshot"}'

Javascript

const endpoint = "https://production-sfo.browserless.io/chromium/bql";
const token = "YOUR_API_TOKEN_HERE";

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"query":"mutation Screenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(omitBackground:true) {\n    base64\n  }\n}","variables":"","operationName":"Screenshot"})
};

const url = `${endpoint}?token=${token}`;
const response = await fetch(url, options);
const data = await response.json();

console.log(data);

Python

import requests

endpoint = "https://production-sfo.browserless.io/chromium/bql"
query_string = {
    "token": "YOUR_API_TOKEN_HERE",
}
headers = {
    "Content-Type": "application/json",
}
payload = {
    "query": "mutation Screenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(omitBackground:true) {\n    base64\n  }\n}",
    "variables": None,
    "operationName": "Screenshot",
}

response = requests.post(endpoint, params=query_string, headers=headers, json=payload)
print(response.json())

Java

String url = "https://production-sfo.browserless.io/chromium/bql";
String token = "YOUR_API_TOKEN_HERE";
String endpoint = String.format("%s?token=%s%s%s", url, token);

HttpResponse<String> response = Unirest.post(endpoint)
    .header("Content-Type", "application/json")
    .body({"query":"mutation Screenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(omitBackground:true) {\n    base64\n  }\n}","variables":"","operationName":"Screenshot"})
    .asString();

C#

string url = "https://production-sfo.browserless.io/chromium/bql";
string token = "YOUR_API_TOKEN_HERE";
string endpoint = $"{url}?token={token}";

var payload = new
{
    query = @"mutation Screenshot {
  goto(url: ""https://example.com"") {
    status
  }

  screenshot(omitBackground: true) {
    base64
  }
}",
    variables = "",
    operationName = "Screenshot"
};

using (HttpClient httpClient = new HttpClient())
{
    var jsonPayload = System.Text.Json.JsonSerializer.Serialize(payload);
    var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");
    
    var response = await httpClient.PostAsync(endpoint, content);
    string responseBody = await response.Content.ReadAsStringAsync();
    Console.WriteLine(responseBody);
}

BQL Schemas

For more details on BQL mutations, refer to the BrowserQL Schema reference pages.

Rest API (Without Stealth)

Bot detection

Browserless recommends using our REST API to take screenshots, unless you need to get past bot detectors.

JSON payload

// JSON body
// `options` are the options available via puppeteer's Page.screenshot() method
// (see https://pptr.dev/api/puppeteer.screenshotoptions)
{
  "url": "https://example.com/",
  "options": {
    "fullPage": true,
    "type": "png"
    // Queue the lack of a `path` parameter
  }
}

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

Java

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

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

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

        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());
            Files.copy(response.body(), Paths.get("screenshot.png"), StandardCopyOption.REPLACE_EXISTING);
            System.out.println("Screenshot saved as screenshot.png");
        } catch (Exception e) {
            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/screenshot?token={TOKEN}";

        string jsonData = @"
        {
            ""url"": ""https://example.com/"",
            ""options"": {
                ""fullPage"": true,
                ""type"": ""png""
            }
        }";

        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 imageBytes = await response.Content.ReadAsByteArrayAsync();

            await File.WriteAllBytesAsync("screenshot.png", imageBytes);

            Console.WriteLine("Screenshot saved as screenshot.png");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}