Appearance
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. |
disableCSSAnimation | false | Disables any CSS animation-related properties e.g animation-* and transition-* |
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"
}
Example 3: Add metadata(EXIF) to the captured 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:
- ID attributes, for example,
<div id="invoice">
. - Regular CSS selectors.
- ID attributes, for example,
- 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. |
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
}
}
]
}