/screenshot API

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 view the complete Screenshot API OpenAPI specification.

bot detection

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

Example

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

Configuration Options

Browserless provides you an extensive set of options for you customize this API to your unique needs, we have discussed some of the configurations below:

Setting HTML content

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

danger

• When this propriety is set, the url propriety must not be present.
• Browserless does't allow setting a options.path for /screenshot API.

JSON payload

// JSON body
// `options` are the options available via puppeteer's Page.screenshot() method
// (see our Open API documentation)
{
  "url": "https://example.com/",
  "options": {
    "type": "webp",
    "omitBackground": true
  }
}

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": {
    "type": "webp",
    "omitBackground": true
  }
}' \
  --output "screenshot.webp"

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: {
    type: "webp",
    omitBackground: true
  }
};

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.webp", Buffer.from(imageBuffer));
  console.log("Screenshot saved as screenshot.webp");
};

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": {
        "type": "webp",
        "omitBackground": True
    }
}

response = requests.post(url, headers=headers, json=data)

with open("screenshot.webp", "wb") as file:
    file.write(response.content)

print("Screenshot saved as screenshot.webp")

Java

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

public class TakeWebpScreenshot {
    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": {
                "type": "webp",
                "omitBackground": true
            }
        }
        """;

        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.webp"), StandardCopyOption.REPLACE_EXISTING);
            System.out.println("Screenshot saved as screenshot.webp");
        } 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"": {
                  ""type"": ""webp"",
                  ""omitBackground"": true
              }
          }";

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

Adding custom styles and scripts

Browserless offers ways to load additional stylesheets and script tags to the page.

JSON payload

{
  "url": "https://example.com/",
  "addScriptTag": [
    { "url": "https://code.jquery.com/jquery-3.7.1.min.js" },
    { "content": "document.querySelector(`h1`).innerText = `Hello Word!`" }
  ],
  "addStyleTag": [
    {
      "content": "body { height: 100vh;  background: linear-gradient(45deg, #da5a44, #a32784);}"
    },
    {
      "url": "https://interactive-examples.mdn.mozilla.net/live-examples/css-examples/text-decoration/text-decoration-color.css"
    }
  ]
}

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/",
  "addScriptTag": [
    { "url": "https://code.jquery.com/jquery-3.7.1.min.js" },
    { "content": "document.querySelector(`h1`).innerText = `Hello Word!`" }
  ],
  "addStyleTag": [
    {
      "content": "body { height: 100vh; background: linear-gradient(45deg, #da5a44, #a32784); }"
    },
    {
      "url": "https://interactive-examples.mdn.mozilla.net/live-examples/css-examples/text-decoration/text-decoration-color.css"
    }
  ]
}' \
  --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/",
  addScriptTag: [
    { url: "https://code.jquery.com/jquery-3.7.1.min.js" },
    { content: "document.querySelector(`h1`).innerText = `Hello Word!`" }
  ],
  addStyleTag: [
    {
      content: "body { height: 100vh; background: linear-gradient(45deg, #da5a44, #a32784); }"
    },
    {
      url: "https://interactive-examples.mdn.mozilla.net/live-examples/css-examples/text-decoration/text-decoration-color.css"
    }
  ]
};

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/",
    "addScriptTag": [
        { "url": "https://code.jquery.com/jquery-3.7.1.min.js" },
        { "content": "document.querySelector(`h1`).innerText = `Hello Word!`" }
    ],
    "addStyleTag": [
        {
            "content": "body { height: 100vh; background: linear-gradient(45deg, #da5a44, #a32784); }"
        },
        {
            "url": "https://interactive-examples.mdn.mozilla.net/live-examples/css-examples/text-decoration/text-decoration-color.css"
        }
    ]
}

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 TakeStyledScreenshot {
    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/",
            "addScriptTag": [
                { "url": "https://code.jquery.com/jquery-3.7.1.min.js" },
                { "content": "document.querySelector(`h1`).innerText = `Hello Word!`" }
            ],
            "addStyleTag": [
                {
                    "content": "body { height: 100vh; background: linear-gradient(45deg, #da5a44, #a32784); }"
                },
                {
                    "url": "https://interactive-examples.mdn.mozilla.net/live-examples/css-examples/text-decoration/text-decoration-color.css"
                }
            ]
        }
        """;

        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/"",
                ""addScriptTag"": [
                    { ""url"": ""https://code.jquery.com/jquery-3.7.1.min.js"" },
                    { ""content"": ""document.querySelector(`h1`).innerText = `Hello Word!`"" }
                ],
                ""addStyleTag"": [
                    {
                        ""content"": ""body { height: 100vh; background: linear-gradient(45deg, #da5a44, #a32784); }""
                    },
                    {
                        ""url"": ""https://interactive-examples.mdn.mozilla.net/live-examples/css-examples/text-decoration/text-decoration-color.css""
                    }
                ]
            }";

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

Additional Configuration Options

The /screenshot API supports additional configuration options that are shared across multiple REST API endpoints. See the Request Configuration page for detailed documentation on:

• Waiting for Things: Wait for events, functions, selectors, or timeouts before capturing the screenshot
• Navigation Options: Customize navigation behavior using gotoOptions
• Rejecting Undesired Requests: Block specific resources using rejectResourceTypes and rejectRequestPattern
• Continue on Error: Use bestAttempt to proceed when async events fail or timeout