# 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](https://docs.launchbrightly.com/product-screenshots-api/remove-elements), [annotate](https://docs.launchbrightly.com/product-screenshots-api/annotate-image), and [style the image](https://docs.launchbrightly.com/product-screenshots-api/style-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](https://docs.launchbrightly.com/product-screenshots-api/export-screenshots). 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](https://docs.launchbrightly.com/product-screenshots-api/options).

## Examples

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

### Example 1: Screenshot 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
            }
        }
    ]
}
```

##### Condition: Invalid selector syntax found

##### Code: `422`

See Example

```json
{
    "errors": [
        "Invalid selectors found: body >>> div"
    ]
}
```

## 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:

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.