Screenshots

The screenshot mutation navigates to a URL and captures a screenshot. Browserless returns the image as a base64-encoded png, jpg, or webp.

Basic Usage

Navigate to a URL and capture the page. Wait for elements to load before capturing to avoid blank or incomplete screenshots.

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": {},
    "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);
}

Setting HTML Content

The content mutation sets the page HTML directly, without navigating to a URL. Use it to screenshot dynamically generated markup.

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": {},
    "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);
}

Element-specific Screenshots

The selector parameter captures a specific element instead of the full page. Use it to focus on a component, widget, or section.

BQL Query

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

  screenshot(selector: "h1") {
    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 ElementScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(selector: \"h1\") {\n    base64\n  }\n}","variables":{},"operationName":"ElementScreenshot"}'

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 ElementScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(selector: \"h1\") {\n    base64\n  }\n}","variables":{},"operationName":"ElementScreenshot"})
};

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 ElementScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(selector: \"h1\") {\n    base64\n  }\n}",
    "variables": {},
    "operationName": "ElementScreenshot",
}

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", url, token);

HttpResponse<String> response = Unirest.post(endpoint)
    .header("Content-Type", "application/json")
    .body("{\"query\":\"mutation ElementScreenshot {\\n  goto(url: \\\"https://example.com\\\") {\\n    status\\n  }\\n\\n  screenshot(selector: \\\"h1\\\") {\\n    base64\\n  }\\n}\",\"variables\":\"\",\"operationName\":\"ElementScreenshot\"}")
    .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 ElementScreenshot {
  goto(url: ""https://example.com"") {
    status
  }

  screenshot(selector: ""h1"") {
    base64
  }
}",
    variables = "",
    operationName = "ElementScreenshot"
};

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

Transparent Background Screenshots

Set omitBackground: true to capture a transparent background instead of the default white. Requires type: png. JPEG does not support transparency.

BQL Query

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

  screenshot(omitBackground: true, type: png) {
    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 TransparentScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(omitBackground: true, type: png) {\n    base64\n  }\n}","variables":{},"operationName":"TransparentScreenshot"}'

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 TransparentScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(omitBackground: true, type: png) {\n    base64\n  }\n}","variables":{},"operationName":"TransparentScreenshot"})
};

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 TransparentScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(omitBackground: true, type: png) {\n    base64\n  }\n}",
    "variables": {},
    "operationName": "TransparentScreenshot",
}

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", url, token);

HttpResponse<String> response = Unirest.post(endpoint)
    .header("Content-Type", "application/json")
    .body("{\"query\":\"mutation TransparentScreenshot {\\n  goto(url: \\\"https://example.com\\\") {\\n    status\\n  }\\n\\n  screenshot(omitBackground: true, type: png) {\\n    base64\\n  }\\n}\",\"variables\":\"\",\"operationName\":\"TransparentScreenshot\"}")
    .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 TransparentScreenshot {
  goto(url: ""https://example.com"") {
    status
  }

  screenshot(omitBackground: true, type: png) {
    base64
  }
}",
    variables = "",
    operationName = "TransparentScreenshot"
};

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

Clipped Region Screenshots

The clip parameter captures a rectangular region defined by pixel coordinates. Use it when the target area does not correspond to a single CSS selector.

BQL Query

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

  screenshot(clip: { x: 100, y: 200, width: 800, height: 600 }) {
    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 ClippedScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(clip: { x: 100, y: 200, width: 800, height: 600 }) {\n    base64\n  }\n}","variables":{},"operationName":"ClippedScreenshot"}'

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 ClippedScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(clip: { x: 100, y: 200, width: 800, height: 600 }) {\n    base64\n  }\n}","variables":{},"operationName":"ClippedScreenshot"})
};

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 ClippedScreenshot {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  screenshot(clip: { x: 100, y: 200, width: 800, height: 600 }) {\n    base64\n  }\n}",
    "variables": {},
    "operationName": "ClippedScreenshot",
}

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", url, token);

HttpResponse<String> response = Unirest.post(endpoint)
    .header("Content-Type", "application/json")
    .body("{\"query\":\"mutation ClippedScreenshot {\\n  goto(url: \\\"https://example.com\\\") {\\n    status\\n  }\\n\\n  screenshot(clip: { x: 100, y: 200, width: 800, height: 600 }) {\\n    base64\\n  }\\n}\",\"variables\":\"\",\"operationName\":\"ClippedScreenshot\"}")
    .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 ClippedScreenshot {
  goto(url: ""https://example.com"") {
    status
  }

  screenshot(clip: { x: 100, y: 200, width: 800, height: 600 }) {
    base64
  }
}",
    variables = "",
    operationName = "ClippedScreenshot"
};

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

Next Steps

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.