Capture Screenshot

The LaunchBrightly Product Screenshots API enables you to effortlessly capture high-quality screenshots of websites with precision and flexibility. When making a request, you have full control over the browser's rendering behavior, including customization of viewport settings, styling, and actions performed before the screenshot is captured.

Additionally, you can remove unwanted elements, annotate, and style the image to suit your needs. The API also offers flexibility in output management, allowing you to either retrieve the screenshot as a base64-encoded image or save it directly to your cloud storage destination. This makes the API ideal for use cases like creating product previews, generating styled visuals, or automating website content capture.

Getting started

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

Request

See Example

POST /screenshot

json

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

Checkout out the full reference.

Examples

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

Example 1: Sreenshot of a section of page using selector

See Example

POST /screenshot

json

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

Example 2: Screenshot with specific viewport width and height

See Example

POST /screenshot

json

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

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

See Example

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`

See 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`

See Example

json

{
    "summary": {
        "total": 1,
        "success": 0,
        "pending": 0,
        "failed": 1
    },
    "screenshots": [
        {
            "id": "7181da86-d70c-467c-acbd-bec7b85f9349",
            "jobId": "ef023ffe-a8c1-4178-85ad-5a2cc3bc4011",
            "status": "failed",
            "error": {
                "message": "The following selector(s) were either not found or timed out for field: 'elementSelector', selectors: bodyx",
                "type": "ElementNotFound",
                "meta": {
                    "type": "elementSelector",
                    "selectors": [
                        "bodyx"
                    ]
                }
            },
            "createdAt": "2025-01-11T01:21:41.974Z",
            "updatedAt": "2025-01-11T01:21:47.706Z",
            "retryCount": 1,
            "raw": {
                "filesize": null,
                "url": null,
                "hash": null
            },
            "styled": {
                "filesize": null,
                "url": null,
                "hash": null
            }
        }
    ]
}

Get capture status

GET /screenshot/:id

Request

Data constraints

A valid :id is required.

Success Response

Condition: If everything is OK

Code: `200`

See Example

json

{
    "summary": {
        "total": 1,
        "success": 1,
        "pending": 0,
        "failed": 0
    },
    "screenshots": [
        {
            "id": "267be4b9-ba03-4130-a334-9783cc8dadc3",
            "jobId": "cd6be494-f659-48ca-9524-278a3670db48",
            "status": "completed",
            "message": "Your screenshot has been generated successfully",
            "warnings": [],
            "createdAt": "2025-01-11T01:22:25.892Z",
            "updatedAt": "2025-01-11T01:22:37.728Z",
            "retryCount": 1,
            "raw": {
                "filesize": 4147096,
                "url": "https://lb-api-screenshots.s3.us-east-1.amazonaws.com/Prod/2025-01-11/raw-267be4b9-ba03-4130-a334-9783cc8dadc3.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20250111%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250111T012247Z&X-Amz-Expires=86400&X-Amz-Signature=36b2cc98b283edbb542f507df52b38aefabd10c07cab87aa18dd487a4702b593&X-Amz-SignedHeaders=host&x-id=GetObject",
                "hash": "cd9b7da099c8a8023fc1f574b0a2974ecf7433092e8c32bd1141ebea1dee1c56"
            },
            "styled": {
                "filesize": null,
                "url": null,
                "hash": null
            }
        }
    ]
}

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

If you would like to capture more than just one screenshot at a time. Send an array of objects as payload:

POST /screenshot

Request

See Example

json

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

Response

See Example

json

{
  "id": "d1f024d4-bd73-437e-8cbc-d10b798590fe",
  "screenshot": [
    {
      "id": "56b01328-5538-43be-9e66-809b7345e505",
      "createdAt": "2024-09-18T12:02:23.186Z",
      "updatedAt": "2024-09-18T12:02:23.186Z"
    },
    {
      "id": "2a21c140-a7fb-49bf-bee6-9b8595f770f7",
      "createdAt": "2024-09-18T12:02:23.188Z",
      "updatedAt": "2024-09-18T12:02:23.188Z"
    }
  ]
}

Get capture status in bulk

POST /screenshot/:id

Response

See Example

json

{
  "summary": {
    "total": 2,
    "success": 2,
    "pending": 0,
    "failed": 0
  },
  "screenshots": [
    {
      "id": "2a21c140-a7fb-49bf-bee6-9b8595f770f7",
      "jobId": "d1f024d4-bd73-437e-8cbc-d10b798590fe",
      "status": "completed",
      "message": "Your screenshot has been generated successfully",
      "warnings": [],
      "createdAt": "2024-09-18T12:02:23.188Z",
      "updatedAt": "2024-09-18T12:02:34.070Z",
      "retryCount": 1,
      "raw": {
        "filesize": 7645,
        "url": "https://lb-api-screenshots.s3.us-east-1.amazonaws.com/Dev_Hyder/2024-09-18/raw-2a21c140-a7fb-49bf-bee6-9b8595f770f7.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20240918%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240918T120249Z&X-Amz-Expires=86400&X-Amz-Signature=270a701466a0be6c5edaa04c2e3b74223a959862468cd69ba18890cf45361169&X-Amz-SignedHeaders=host&x-id=GetObject",
        "hash": "de597dc902659ba685c6400f6785d71844b82a04261fedfa77534beaf4db2fd1"
      },
      "styled": {
        "filesize": null,
        "url": null,
        "hash": null
      }
    },
    {
      "id": "56b01328-5538-43be-9e66-809b7345e505",
      "jobId": "d1f024d4-bd73-437e-8cbc-d10b798590fe",
      "status": "completed",
      "message": "Your screenshot has been generated successfully",
      "warnings": [],
      "createdAt": "2024-09-18T12:02:23.186Z",
      "updatedAt": "2024-09-18T12:02:35.507Z",
      "retryCount": 1,
      "raw": {
        "filesize": 89701,
        "url": "https://lb-api-screenshots.s3.us-east-1.amazonaws.com/Dev_Hyder/2024-09-18/raw-56b01328-5538-43be-9e66-809b7345e505.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20240918%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240918T120249Z&X-Amz-Expires=86400&X-Amz-Signature=518004705267d51e2c327c11eeab2ccb29b14dc93f9af5bc532b655287fb6e2e&X-Amz-SignedHeaders=host&x-id=GetObject",
        "hash": "3244cf8fa645fc760462a60a759372b6b623031f231f9d94482733583fcedad0"
      },
      "styled": {
        "filesize": null,
        "url": null,
        "hash": null
      }
    }
  ]
}

Limitation of sending bulk requests

The API allows you to submit up to 100 screenshot capture jobs in a single request. If you have more than 100 jobs, you will need to send multiple requests.

To check the progress of multiple job IDs, separate them with commas, as shown below:

GET /screenshot/:jobId1,:jobId2,:jobId3

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.

Capture Screenshot ​

Getting started ​

Request ​

Examples ​

Example 1: Sreenshot of a section of page using selector ​

Example 2: Screenshot with specific viewport width and height ​

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

Success Response ​

Condition: If everything is OK ​

Code: 202 ​

Error Response(s) ​

Condition: The elementSelector is invalid or missing ​

Code: 500 ​

Get capture status ​

Request ​

Data constraints ​

Success Response ​

Condition: If everything is OK ​

Code: 200 ​

Capture screenshots in bulk ​

Request ​

Response ​

Get capture status in bulk ​

Response ​

Limitation of sending bulk requests ​

Selector Priority ​

Capture Screenshot

Getting started

Request

Examples

Example 1: Sreenshot of a section of page using selector

Example 2: Screenshot with specific viewport width and height

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

Success Response

Condition: If everything is OK

Code: `202`

Error Response(s)

Condition: The `elementSelector` is invalid or missing

Code: `500`

Get capture status

Request

Data constraints

Success Response

Condition: If everything is OK

Code: `200`

Capture screenshots in bulk

Request

Response

Get capture status in bulk

Response

Limitation of sending bulk requests

Selector Priority