Skip to content
On this page

Capture Screenshot

The core functionality of the LaunchBrightly Product Screenshots API is to capture screenshots and as you make this request you have control over what the browser "looks like" and how you want it rendered. Including the ability to pick where you want the output image to be saved (if not just returned as a base64image). You are likely to use have removed elements, taken a set of actions, and perhaps even annotated and styled the image before it is saved to your cloud.

The bare minimum required to take a screenshot

POST /screenshot

Request

json
{
  "url": "https://convertkit.baremetrics.com/stats/arr",
  "elementSelector": [
    ".main-graph",
    ".an_alternate_selector"
  ]
}

The screenshot API allows you to accurately and securely generate screenshots of your web apps at scale.

List of supported attributes

OptionDefault value (if not specified)description
width1200Viewport width
height900Viewport height
userAgentMozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36User agent
timeout60000Maximum waiting time (ms) to capture a screenshot
prefersColorSchemelightdark/light mode
cloud.uploads3Save images to Amazon S3 or Cloudflare R2 bucket
cloud.fileObjecte.g /path/acme/light-arr.pngSets the path including file name of your screenshot
deviceScaleFactor2retina
responseTypebase64imagevalues: base64image/queue
acceptLanguageen-USSets an Accept-Language header on requests to the target URL
captureBeyondViewporttrueCapture the hidden part of the selector (outside of the viewport)
geolocation.latitudenullSets the latitude used to emulate the Geolocation API
geolocation.longitudenullSets the longitude used to emulate the Geolocation API
geolocation.accuracy100Sets the accuracy of the Geolocation API, in metres
stepImages-Allow visual debugging with snapshots of page.

Usage

Below is a series of examples demonstrating various properties of the screenshot API endpoint.

Example 1: Sreenshot of a section of page using selector

json
{
  "url": "https://convertkit.baremetrics.com/stats/arr",
  "elementSelector": [
    ".main-graph",
    ".container.alternate-selector"
  ],
  "responseType": "queue"
}

Example 2: Screenshot with specific viewport width and height

json
{
  "url": "https://convertkit.baremetrics.com/stats/arr",
  "elementSelector": [
    ".main-graph",
    ".container.alternate-selector"
  ],
  "width": 800,
  "height": 400,
  "responseType": "queue"
}

Success Response

The response will be a JSON object acknowledging your request was received and queued.

Condition: If everything is OK
Code: 202
Example:
json
{
  "id": "6d0fc9ea-acba-4230-a643-db02e6804ebb",
  "createdAt": "2023-04-24T18:50:09.326Z",
  "updatedAt": "2023-04-24T18:50:09.326Z",
  "message": "Your screenshot request has been successfully queued."
}

Error Response(s)

Condition: The elementSelector is invalid or missing
Code: 500
Content Example:
json
{
  "status": "failed",
  "message": "The elementSelector body > div.container > div.container--inner > section > main > section.aux_charts.x,.aux_charts.x is either not present or took too long to render.",
  "createdAt": "2023-06-20T11:55:39.594Z",
  "updatedAt": "2023-06-20T11:57:23.033Z",
  "url": {
    "styled": null,
    "raw": null
  }
}

Selector Priority

Both the fields elementSelector and the steps.[].selectors allows you to specify alternate selectors that lead to the selection of a single element. Specifying alternative selectors helps to improve reliability of the screenshot API as some selectors might get outdated over time.

Currently, we support CSS selectors, ARIA selectors (start with aria/), XPath selectors (start with xpath/).

The Screenshot API looks for selectors in the following order:

  1. ARIA selector if found.
  2. CSS selectors with the following priority:
    1. ID attributes, for example, <div id="invoice">.
    2. Regular CSS selectors.
  3. XPath selectors.

Get capture status

GET /screenshot/:id

Request

Data constraints

A valid :id is required.

Success Response

Condition: If everything is OK
Code: 200
Content Example:
json
{
  "status": "completed",
  "message": "Your screenshot has been generated successfully",
  "createdAt": "2023-05-30T08:36:58.787Z",
  "updatedAt": "2023-05-30T08:37:13.629Z",
  "url": {
    "raw": "https://s3.us-east-1.amazonaws.com/2023-05-30/68dae252-4736-4e65-bb08-44824c2994c4.png",
    "styled": "https://s3.us-east-1.amazonaws.com/2023-05-30/68dae252-4736-4e65-bb08-44824c2994c4_styled.png"
  }
}

The different status values are:

statusDescription
pendingThe screenshot capture request is queued
completedThe screenshot capture completed successfully and available to download in url
failedThe screenshot capture failed. Refer to message for failure reason.

Capture screenshots in bulk

We provide dedicated endpoints for capturing screenshots in bulk. Please send your payload as an array of objects.

POST /screenshot/bulk

Request

json
[
  {
    "url": "https://convertkit.baremetrics.com/stats/arr",
    "responseType": "queue",
    "elementSelector": [
      ".main-graph"
    ]
  },
  {
    "url": "https://convertkit.baremetrics.com/stats/arr",
    "responseType": "queue",
    "elementSelector": [
      "body > div.container > div.container--inner > section > main > section > div.metric-stat > div > h1"
    ]
  }
]

Capture screenshots in bulk

We provide dedicated endpoints for capturing screenshots in bulk. Please send your payload as an array of objects.

POST /screenshot/bulk

Request

json
[
  {
    "url": "https://convertkit.baremetrics.com/stats/arr",
    "responseType": "queue",
    "elementSelector": [
      ".main-graph"
    ]
  },
  {
    "url": "https://convertkit.baremetrics.com/stats/arr",
    "responseType": "queue",
    "elementSelector": [
      "body > div.container > div.container--inner > section > main > section > div.metric-stat > div > h1"
    ]
  }
]

Get capture status in bulk

POST /screenshot/bulk/:id

Response

json
{
  "summary": {
    "total": 2,
    "success": 2,
    "pending": 0,
    "failed": 0
  },
  "screenshots": [
    {
      "id": "3db114cc-268b-472a-9e87-de44942bacc5",
      "status": "completed",
      "message": "Your screenshot has been generated successfully",
      "warnings": [],
      "createdAt": "2024-01-25T18:35:03.736Z",
      "updatedAt": "2024-01-25T18:35:06.430Z",
      "reference": "",
      "filesize": {
        "raw": 93404,
        "styled": null
      },
      "url": {
        "raw": "https://lb-api-screenshots.s3.us-east-1.amazonaws.com/Staging/2024-01-25/raw-3db114cc-268b-472a-9e87-de44942bacc5.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCBOBPNBEB%2F20240125%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240125T183516Z&X-Amz-Expires=3600&X-Amz-Signature=8fecdf813948884ee25cbd997332ca6a6e8f313cdc4e761658e1ec3aeed381c3&X-Amz-SignedHeaders=host&x-id=GetObject",
        "styled": null
      }
    },
    {
      "id": "bf0ff63e-acc2-4b92-a090-9004d3295ace",
      "status": "completed",
      "message": "Your screenshot has been generated successfully",
      "warnings": [],
      "createdAt": "2024-01-25T18:35:03.797Z",
      "updatedAt": "2024-01-25T18:35:09.231Z",
      "reference": "",
      "filesize": {
        "raw": 9315,
        "styled": null
      },
      "url": {
        "raw": "https://lb-api-screenshots.s3.us-east-1.amazonaws.com/Staging/2024-01-25/raw-bf0ff63e-acc2-4b92-a090-9004d3295ace.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCBOBPNBEB%2F20240125%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240125T183516Z&X-Amz-Expires=3600&X-Amz-Signature=6e242b09cb56b857ca172fee6cf03523ccddecedd8d0dbe494a2b9dccee62a24&X-Amz-SignedHeaders=host&x-id=GetObject",
        "styled": null
      }
    }
  ]
}