PDF Generation

The pdf mutation navigates to a URL and generates a PDF. Browserless returns the file as a base64-encoded string with options for page format, margins, headers, footers, and background printing.

Basic Usage

Navigate to a URL and capture the page as a PDF. Wait for elements to load before generating to avoid incomplete content.

BQL Query

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

  pdf(displayHeaderFooter: true, printBackground: false, format: a0) {
    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 PDF {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  pdf(displayHeaderFooter: true, printBackground: false, format: a0) {\n    base64\n  }\n}","variables":{},"operationName":"PDF"}'

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 PDF {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  pdf(displayHeaderFooter: true, printBackground: false, format: a0) {\n    base64\n  }\n}","variables":{},"operationName":"PDF"})
};

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 PDF {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  pdf(displayHeaderFooter: true, printBackground: false, format: a0) {\n    base64\n  }\n}",
    "variables": {},
    "operationName": "PDF",
}

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 PDF {\n  goto(url: \"https://example.com\") {\n    status\n  }\n\n  pdf(displayHeaderFooter: true, printBackground: false, format: a0) {\n    base64\n  }\n}","variables":{},"operationName":"PDF"})
    .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 PDF {
  goto(url: ""https://example.com"") {
    status
  }

  pdf(displayHeaderFooter: true, printBackground: false, format: a0) {
    base64
  }
}",
    variables = "",
    operationName = "PDF"
};

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

Setting HTML Content

The content mutation sets the page HTML directly, without navigating to a URL. Use it to generate PDFs from dynamic or server-rendered markup.

BQL Query

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

  pdf(displayHeaderFooter: true, printBackground: false, format: a0) {
    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 PDF {\ncontent(html: \"<h1>Hello, World!</h1>\") {\n  status\n}\n\npdf(displayHeaderFooter: true, printBackground: false, format: a0) {\n  base64\n}\n}","variables":{},"operationName":"PDF"}'

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 PDF {\ncontent(html: \"<h1>Hello, World!</h1>\") {\n  status\n}\n\npdf(displayHeaderFooter: true, printBackground: false, format: a0) {\n  base64\n}\n}","variables":{},"operationName":"PDF"})
};

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 PDF {\ncontent(html: \"<h1>Hello, World!</h1>\") {\n  status\n}\n\npdf(displayHeaderFooter: true, printBackground: false, format: a0) {\n  base64\n}\n}",
    "variables": {},
    "operationName": "PDF",
}

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 PDF {\ncontent(html: \"<h1>Hello, World!</h1>\") {\n  status\n}\n\npdf(displayHeaderFooter: true, printBackground: false, format: a0) {\n  base64\n}\n}","variables":{},"operationName":"PDF"})
    .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 PDF {
content(html: ""<h1>Hello, World!</h1>"") {
  status
}

pdf(displayHeaderFooter: true, printBackground: false, format: a0) {
  base64
}
}",
    variables = "",
    operationName = "PDF"
};

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

Adding Header and Footer Templates

Custom header and footer templates let you inject dynamic content into PDFs. Templates support special CSS classes: pageNumber, totalPages, title, url, and date.

Font Size

Specify font sizes explicitly in header and footer templates (e.g., font-size: 12pt). The default text size is too small to read in most PDF viewers.

BQL Query

mutation addFooterAndHeaderToPDF {
  goto(url: "https://www.example.com", waitUntil: networkIdle) {
    status
  }
  invoice: pdf(
    format: a4
    displayHeaderFooter: true
    headerTemplate: "<div style='font-size:12pt; line-height:1.2; width:100%; text-align:center; padding-top:2mm;'><span class='title'></span></div>"
    footerTemplate: "<div style='font-size:11pt; line-height:1.2; width:100%; text-align:center; padding-bottom:2mm;'><span class='pageNumber'></span>/<span class='totalPages'></span></div>"
    printBackground: 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 addFooterAndHeaderToPDF {\n  goto(url: \"https://www.example.com\", waitUntil: networkIdle) {\n    status\n  }\n  invoice: pdf(\n    format: a4\n    displayHeaderFooter: true\n    headerTemplate: \"<div style='\''font-size:12pt; line-height:1.2; width:100%; text-align:center; padding-top:2mm;'\''><span class='\''title'\''></span></div>\"\n    footerTemplate: \"<div style='\''font-size:11pt; line-height:1.2; width:100%; text-align:center; padding-bottom:2mm;'\''><span class='\''pageNumber'\''></span>/<span class='\''totalPages'\''></span></div>\"\n    printBackground: true\n  ) {\n    base64\n  }\n}","variables":{},"operationName":"addFooterAndHeaderToPDF"}'

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 addFooterAndHeaderToPDF {\n  goto(url: \"https://www.example.com\", waitUntil: networkIdle) {\n    status\n  }\n  invoice: pdf(\n    format: a4\n    displayHeaderFooter: true\n    headerTemplate: \"<div style='font-size:12pt; line-height:1.2; width:100%; text-align:center; padding-top:2mm;'><span class='title'></span></div>\"\n    footerTemplate: \"<div style='font-size:11pt; line-height:1.2; width:100%; text-align:center; padding-bottom:2mm;'><span class='pageNumber'></span>/<span class='totalPages'></span></div>\"\n    printBackground: true\n  ) {\n    base64\n  }\n}","variables":{},"operationName":"addFooterAndHeaderToPDF"})
};

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 addFooterAndHeaderToPDF {\n  goto(url: \"https://www.example.com\", waitUntil: networkIdle) {\n    status\n  }\n  invoice: pdf(\n    format: a4\n    displayHeaderFooter: true\n    headerTemplate: \"<div style='font-size:12pt; line-height:1.2; width:100%; text-align:center; padding-top:2mm;'><span class='title'></span></div>\"\n    footerTemplate: \"<div style='font-size:11pt; line-height:1.2; width:100%; text-align:center; padding-bottom:2mm;'><span class='pageNumber'></span>/<span class='totalPages'></span></div>\"\n    printBackground: true\n  ) {\n    base64\n  }\n}",
    "variables": {},
    "operationName": "addFooterAndHeaderToPDF",
}

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 addFooterAndHeaderToPDF {\\n  goto(url: \\\"https://www.example.com\\\", waitUntil: networkIdle) {\\n    status\\n  }\\n  invoice: pdf(\\n    format: a4\\n    displayHeaderFooter: true\\n    headerTemplate: \\\"<div style='font-size:12pt; line-height:1.2; width:100%; text-align:center; padding-top:2mm;'><span class='title'></span></div>\\\"\\n    footerTemplate: \\\"<div style='font-size:11pt; line-height:1.2; width:100%; text-align:center; padding-bottom:2mm;'><span class='pageNumber'></span>/<span class='totalPages'></span></div>\\\"\\n    printBackground: true\\n  ) {\\n    base64\\n  }\\n}\",\"variables\":\"\",\"operationName\":\"addFooterAndHeaderToPDF\"}")
    .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 addFooterAndHeaderToPDF {
  goto(url: ""https://www.example.com"", waitUntil: networkIdle) {
    status
  }
  invoice: pdf(
    format: a4
    displayHeaderFooter: true
    headerTemplate: ""<div style='font-size:12pt; line-height:1.2; width:100%; text-align:center; padding-top:2mm;'><span class='title'></span></div>""
    footerTemplate: ""<div style='font-size:11pt; line-height:1.2; width:100%; text-align:center; padding-bottom:2mm;'><span class='pageNumber'></span>/<span class='totalPages'></span></div>""
    printBackground: true
  ) {
    base64
  }
}",
    variables = "",
    operationName = "addFooterAndHeaderToPDF"
};

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

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.