Screenshots

The screenshot mutation 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).

On this collection we'll look at:

• Basic Usage
• Setting HTML content

BQL Schemas

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

Rest API

Taking Screenshots can also be done with Browserless Rest API. For endpoint details, parameters, and code samples, see the Browserless REST API.

Basic Usage

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

Waiting for Elements

For more reliable screenshots, it's important to wait for the site and elements to be ready before capturing. Learn more about BrowserQL's built-in wait methods in our Waiting for Things documentation.

Setting HTML Content

You can set the HTML content of the page to render dynamically generated content.

BQL Query

mutation Screenshot {
  content(html: "<h1>Hello, World!</h1>") {
    status
  }

  screenshot(type: webp) {
    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  content(html: \"<h1>Hello, World!</h1>\") {\n    status\n  }\n\n  screenshot(type: webp) {\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  content(html: \"<h1>Hello, World!</h1>\") {\n    status\n  }\n\n  screenshot(type: webp) {\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  content(html: \"<h1>Hello, World!</h1>\") {\n    status\n  }\n\n  screenshot(type: webp) {\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  content(html: \"<h1>Hello, World!</h1>\") {\n    status\n  }\n\n  screenshot(type: webp) {\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 {
  content(html: ""<h1>Hello, World!</h1>"") {
    status
  }

  screenshot(type: webp) {
    base64
  }
}",
    variables = "",
    operationName = "Screenshot"
};

using (var client = new HttpClient())
{
    var jsonPayload = System.Text.Json.JsonSerializer.Serialize(payload);
    var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

    var response = await client.PostAsync(endpoint, content);
    string responseBody = await response.Content.ReadAsStringAsync();
    
    Console.WriteLine(responseBody);
}

Next Steps

Ready to take your screenshot automation to the next level? Explore these key areas:

Waiting Properly

Learn about BrowserQL's built-in waiters for more reliable automations.

Reject Unnecessary Resources

Block ads, images, and other non-essential content to improve performance.

Best BQL Practices

Master essential patterns for reliable and maintainable browser automation.