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

Option	Default value (if not specified)	description
width	1200	Viewport width
height	900	Viewport height
userAgent	Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36	User agent
timeout	60000	Maximum waiting time (ms) to capture a screenshot
maxRetryCount	1	No. of times to retry capturing a screenshot. It is disabled by default (when set to 1)
prefersColorScheme	light	dark/light mode
cloud.upload	s3	Save images to Amazon S3 or Cloudflare R2 bucket
cloud.fileObject	e.g `/path/acme/light-arr.png`	Sets the path including file name of your screenshot
deviceScaleFactor	2	retina
responseType	base64image	values: base64image/queue
acceptLanguage	en-US	Sets an `Accept-Language` header on requests to the target URL
fullPage	false	Capture a screenshot of the whole page.
captureBeyondViewport	true	Capture the hidden part of the selector (outside of the viewport)
geolocation.latitude	null	Sets the latitude used to emulate the Geolocation API
geolocation.longitude	null	Sets the longitude used to emulate the Geolocation API
geolocation.accuracy	100	Sets the accuracy of the Geolocation API, in metres
stepImages	-	Allow visual debugging with snapshots of page.
metadata	-	Add metadata(EXIF) to the captured image. Support up to 5 keys. See example 3.
css.animations	enabled	Configure CSS animation behaviour. Possible values: `enabled`, `disabled` and `runOnce`
css.borderRadius	enabled	Tweak the border-radius CSS property of the element to screenshot. Possible values: `enabled`, `disabled`
elementSelector	-	It is used to select the element to capture a screenshot of.
elementFrame	-

elementFrame is an optional parameter that allows you to capture a screenshot of a specific frame within an iframe. It

Render Options:

`width`

default: 1280

The viewport width of the browser, in pixels.

`height`

default: 1280

The viewport height of the browser, in pixels.

`userAgent`

default: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36

Sets the User-Agent string for the request to avoid bot detection or emulate specific devices.

`timeout`

default: 60000

The maximum time in milliseconds to wait to capture a screenshot. If the page takes longer to load, the request will mark as failed.

`maxRetryCount`

default: 1

The number of times to retry capturing a screenshot. It is disabled by default (when set to 1).

`prefersColorScheme`

default: light

Set the color scheme of the browser. Possible values are light and dark.

`acceptLanguage`

default: en-US

This parameter sets the browser's language to the specified value. It updates the accept-language HTTP header, as well as the navigator.userLanguage and navigator.language properties, to match the specified language.

`elementSelector`

default: Optional

This parameter is used to select the element to capture a screenshot of. It can be a CSS selector, ARIA selector, or XPath.

`elementFrame`

default: Optional

This parameter is used to select the frame within an iframe to capture a screenshot of. If a page contains an iframe, you can interact with that iframe by setting elementFrame: [0]. See this page for more information on how to interact with iframes.

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

POST /screenshot

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

POST /screenshot

json

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

Example 3: Add metadata(EXIF) to the captured screenshot.

POST /screenshot

json

{
  "url": "https://example.org",
  "elementSelector": [
    "body"
  ],
  "metadata": {
    "id": "xxx",
    "description": "Contact form"
  }
}

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:

ARIA selector if found.
CSS selectors with the following priority:
1. ID attributes, for example, <div id="invoice">.
2. Regular CSS selectors.
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:

status	Description
pending	The screenshot capture request is queued
completed	The screenshot capture completed successfully and available to download in `url`
failed	The screenshot capture failed. Refer to `message` for failure reason.