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
- Element-specific Screenshots
- Transparent Background Screenshots
- Clipped Region Screenshots
For more details on BQL mutations, refer to the BrowserQL Schema reference pages.
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
- cURL
- Javascript
- Python
- Java
- C#
mutation Screenshot {
goto(url: "https://example.com") {
status
}
screenshot(omitBackground:true) {
base64
}
}
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"}'
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);
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())
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();
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);
}
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
- cURL
- Javascript
- Python
- Java
- C#
mutation Screenshot {
content(html: "<h1>Hello, World!</h1>") {
status
}
screenshot(type: webp) {
base64
}
}
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"}'
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);
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())
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();
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
Use the selector
parameter to capture screenshots of specific page elements instead of the entire page. This is useful for focusing on particular components, widgets, or sections of a webpage.
- BQL Query
- cURL
- Javascript
- Python
- Java
- C#
mutation ElementScreenshot {
goto(url: "https://example.com") {
status
}
screenshot(selector: "h1") {
base64
}
}
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"}'
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);
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": None,
"operationName": "ElementScreenshot",
}
response = requests.post(endpoint, params=query_string, headers=headers, json=payload)
print(response.json())
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();
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
Use omitBackground: true
to capture screenshots with transparent backgrounds instead of the default white background. This is particularly useful when creating overlays or when you need to composite the screenshot with other images.
- BQL Query
- cURL
- Javascript
- Python
- Java
- C#
mutation TransparentScreenshot {
goto(url: "https://example.com") {
status
}
screenshot(omitBackground: true, type: png) {
base64
}
}
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"}'
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);
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": None,
"operationName": "TransparentScreenshot",
}
response = requests.post(endpoint, params=query_string, headers=headers, json=payload)
print(response.json())
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();
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);
}
Transparent backgrounds only work with PNG format. Make sure to set type: png
when using omitBackground: true
.
Clipped Region Screenshots
Use the clip
parameter to capture a precise rectangular region of the page by specifying exact pixel coordinates. This is useful when you need to capture a specific area that doesn't correspond to a CSS selector.
- BQL Query
- cURL
- Javascript
- Python
- Java
- C#
mutation ClippedScreenshot {
goto(url: "https://example.com") {
status
}
screenshot(clip: { x: 100, y: 200, width: 800, height: 600 }) {
base64
}
}
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"}'
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);
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": None,
"operationName": "ClippedScreenshot",
}
response = requests.post(endpoint, params=query_string, headers=headers, json=payload)
print(response.json())
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();
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
Ready to take your screenshot automation to the next level? Explore these key areas: