/screenshot API

info

Currently, Browserless V2 is available in production via two domains: production-sfo.browserless.io and production-lon.browserless.io

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 check the full Open API schema here.

note

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

Basic Usage

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

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.

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

warning

We do not allow to set a options.path

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

Rejecting Undesired Requests

You can use rejectResourceTypes and rejectRequestPattern to block undesired content, resources and requests.

JSON payload

// Will reject any images and .css files
{
  "url": "https://browserless.io/"
  "rejectResourceTypes": ["image"],
  "rejectRequestPattern": ["/^.*\\.(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://browserless.io/",
  "rejectResourceTypes": ["image"],
  "rejectRequestPattern": ["/^.*\\.(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://browserless.io/",
  rejectResourceTypes: ["image"],
  rejectRequestPattern: ["^.*\\.(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://browserless.io/",
    "rejectResourceTypes": ["image"],
    "rejectRequestPattern": ["^.*\\.(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 TakeScreenshotWithRejections {
    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://browserless.io/",
            "rejectResourceTypes": ["image"],
            "rejectRequestPattern": ["^.*\\\\.(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://browserless.io/"",
                ""rejectResourceTypes"": [""image""],
                ""rejectRequestPattern"": [""^.*\\\\.(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}");
          }
      }
  }

Navigation Options

You can use the gotoOptions to modify the default navigation behavior for the requested URL. The objects mirror Puppeteer's GoToOptions interface.

JSON payload

{
  "url": "https://example.com/",
  "gotoOptions": { "waitUntil": "networkidle2" },
}

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/",
  "gotoOptions": { "waitUntil": "networkidle2" }
}' \
  --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/",
  gotoOptions: { waitUntil: "networkidle2" }
};

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/",
    "gotoOptions": { "waitUntil": "networkidle2" }
}

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 TakeScreenshotWithGotoOptions {
    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/",
            "gotoOptions": { "waitUntil": "networkidle2" }
        }
        """;

        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/"",
                ""gotoOptions"": { ""waitUntil"": ""networkidle2"" }
            }";

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

Continue on Error

You can use bestAttempt to make Browserless attempt to proceed when async events fail or timeout. This includes things like the goto or waitForSelector proprieties in the JSON payload.

JSON payload

{
  "url": "https://example.com/",
  "bestAttempt": true,

  // This would fail without bestAttempt
  "waitForSelector": { "selector": "table", "timeout": 500 }
}

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/",
  "bestAttempt": true,
  "waitForSelector": { "selector": "table", "timeout": 500 }
}' \
  --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/",
  bestAttempt: true,
  waitForSelector: { selector: "table", timeout: 500 }
};

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/",
    "bestAttempt": True,
    "waitForSelector": { "selector": "table", "timeout": 500 }
}

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 TakeScreenshotWithBestAttempt {
    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/",
            "bestAttempt": true,
            "waitForSelector": { "selector": "table", "timeout": 500 }
        }
        """;

        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/"",
                ""bestAttempt"": true,
                ""waitForSelector"": { ""selector"": ""table"", ""timeout"": 500 }
            }";

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

Waiting for Things

Browserless offers 4 different ways to wait for preconditions to be met on page. These are events, functions, selectors and timeouts

waitForEvent

Waits for an event to happen on the page before cotinue

Example

JSON payload

// Will fail since the event never fires
{
  "url": "https://example.com/",
  "waitForEvent": {
    "event": "fullscreenchange",
    "timeout": 5000
  }
}

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/",
  "waitForEvent": {
    "event": "fullscreenchange",
    "timeout": 5000
  }
}' \
  --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/",
  waitForEvent: {
    event: "fullscreenchange",
    timeout: 5000
  }
};

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/",
    "waitForEvent": {
        "event": "fullscreenchange",
        "timeout": 5000
    }
}

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 TakeScreenshotWithWaitForEvent {
    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/",
            "waitForEvent": {
                "event": "fullscreenchange",
                "timeout": 5000
            }
        }
        """;

        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/"",
                ""waitForEvent"": {
                    ""event"": ""fullscreenchange"",
                    ""timeout"": 5000
                }
            }";

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

waitForFunction

Waits for the provided function to return before cotinue. The function can be any valid JavaScript or EcmaScript function, and async functions are supported.

Example

JS function

async () => {
  const res = await fetch("https://jsonplaceholder.typicode.com/todos/1");
  const json = await res.json();

  document.querySelector("h1").innerText = json.title;
};

JSON payload

{
  "url": "https://example.com/",
  "waitForFunction": {
    "fn": "async()=>{let t=await fetch('https://jsonplaceholder.typicode.com/todos/1'),e=await t.json();document.querySelector('h1').innerText=e.title}",
    "timeout": 5000
  }
}

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/",
  "waitForFunction": {
    "fn": "async()=>{let t=await fetch('https://jsonplaceholder.typicode.com/todos/1'),e=await t.json();document.querySelector('h1').innerText=e.title}",
    "timeout": 5000
  }
}' \
  --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/",
  waitForFunction: {
    fn: "async()=>{let t=await fetch('https://jsonplaceholder.typicode.com/todos/1'),e=await t.json();document.querySelector('h1').innerText=e.title}",
    timeout: 5000
  }
};

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/",
    "waitForFunction": {
        "fn": "async()=>{let t=await fetch('https://jsonplaceholder.typicode.com/todos/1'),e=await t.json();document.querySelector('h1').innerText=e.title}",
        "timeout": 5000
    }
}

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 TakeScreenshotWithWaitForFunction {
    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/",
            "waitForFunction": {
                "fn": "async()=>{let t=await fetch('https://jsonplaceholder.typicode.com/todos/1'),e=await t.json();document.querySelector('h1').innerText=e.title}",
                "timeout": 5000
            }
        }
        """;

        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/"",
                ""waitForFunction"": {
                    ""fn"": ""async()=>{let t=await fetch('https://jsonplaceholder.typicode.com/todos/1'),e=await t.json();document.querySelector('h1').innerText=e.title}"",
                    ""timeout"": 5000
                }
            }";

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

waitForSelector

Wait for a selector to appear in page. If at the moment of calling the method the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout milliseconds of waiting, the function will throw.

The object can have any of these values:

• selector: String, required — A valid CSS selector.
• hidden Boolean, optional — Wait for the selected element to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties.
• timeout: Number, optional — Maximum number of milliseconds to wait for the selector before failing.
• visible: Boolean, optional — Wait for the selected element to be present in DOM and to be visible, i.e. to not have display: none or visibility: hidden CSS properties.

Example

JSON payload

// Will fail since the event never fires
{
  "url": "https://example.com/",
  "waitForEvent": {
    "event": "fullscreenchange",
    "timeout": 5000
  }
}

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/",
  "waitForEvent": {
    "event": "fullscreenchange",
    "timeout": 5000
  }
}' \
  --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/",
  waitForEvent: {
    event: "fullscreenchange",
    timeout: 5000
  }
};

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/",
    "waitForEvent": {
        "event": "fullscreenchange",
        "timeout": 5000
    }
}

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 TakeScreenshotWithWaitForEvent {
    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/",
            "waitForEvent": {
                "event": "fullscreenchange",
                "timeout": 5000
            }
        }
        """;

        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/"",
                ""waitForEvent"": {
                    ""event"": ""fullscreenchange"",
                    ""timeout"": 5000
                }
            }";

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