# ScreenshotOne.com Full Documentation

# Bulk Screenshots

import Alert from "@/components/Alert.astro";

## Request

You can use a bulk screenshot-taking feature to take many screenshots in one request.
Send a simple POST HTTP request to `/bulk` path with the list of URLs (HTML or Markdown):

```
POST https://api.screenshotone.com/bulk 

{
    "access_key": "<your access key>"
    "execute": false,
    "optimize": false,
    "options": {"url": "https://example.com", "viewport_width": 1280, "viewport_height": 1024, "block_ads": true}, 
    "requests": [
        {"viewport_width": 360, "viewport_height": 640}, // a screenshot of example.com with a different viewport
        {"url": "https://example.com"},
        {"url": "https://finance.yahoo.com", "block_cookie_banners": true},
        {"html": "<h1>Hello, world!</h1>", "block_ads": false}, 
        {"markdown": "**Yes!**"}
    ]
}
```

The options property contains default options that will be applied to every request. And for every request, you can specify options to override the default values. You can specify all [the regular options you use to take a single screenshot](/docs/options).

You can specify the access key as a query parameter `access_key=<your access key>`, an HTTP header `X-Access-Key: <your access key>`, or in the request's body.

## Response

The response contains an array of screenshot URLs you can use to download the screenshots:

```json
{
    "responses": [
        {"url": "https://api.screenshotone.com/take?url=http://example.com&viewport_width=1280&viewport_height=1024&block_ads=true"},
        {"url": "https://api.screenshotone.com/take?url=https://finance.yahoo.com&viewport_width=1280&viewport_height=1024&block_ads=true&block_cookie_banners=true"},
        {"url": "https://api.screenshotone.com/take?html=<h1>Hello, world!</h1>&viewport_width=1280&viewport_height=1024&block_ads=false&block_cookie_banners=true"}
    ]
}
```

But if you requested to [execute requests](#execute-requests), the result will also contain a summary execution response for each request: 

```
[
    {
        "url": "https://api.screenshotone.com/take?url=http://example.com&viewport_width=1280&viewport_height=1024&block_ads=true",
        "response": {
            "is_successful": true,
            "status": 200,
            "statusText": "OK"
        }
    },
    {
        "url": "https://api.screenshotone.com/take?url=https://finance.yahoo.com&viewport_width=1280&viewport_height=1024&block_ads=true&block_cookie_banners=true",
        "response": {
            "is_successful": true,
            "status": 200,
            "statusText": "OK"
        }
    },
    {
        "url": "https://api.screenshotone.com/take?html=<h1>Hello, world!</h1>&viewport_width=1280&viewport_height=1024&block_ads=false&block_cookie_banners=true",
        "response": {
            "is_successful": true,
            "status": 200,
            "statusText": "OK"
        }
    },
    {
        "url": "https://api.screenshotone.com/take?markdown=**Yes!**&viewport_width=1280&viewport_height=1024&block_ads=false&block_cookie_banners=true",
        "response": {
            "is_successful": true,
            "status": 200,
            "statusText": "OK"
        }
    }
]
```

As you noticed, images are not returned, but in case of an error, the `is_successful` property will be `false`, and you can expect the `body` property to explore the error:

```
[
    {
        "url": "https://api.screenshotone.com/take?url=http://example.com&viewport_width=1280&viewport_height=1024&block_ads=true",
        "response": {
            "is_successful": false,
            "status": 400,
            "statusText": "Bad request", 
            body: {
                "error_code": "concurrency_limit_reached"
                "error_message": "Concurrency limit is reached"
            }
        }
    }
]
```

## Execute requests 

Bulk screenshots are implemented in a lazy loading way. It means that the screenshot is literally taken when you tried to download it, not when you sent a bulk request. If you want to execute each request before you get a response, set the parameter `execute` to `true`:
```
POST https://api.screenshotone.com/bulk 

{
    "access_key": "<your access key>"
    "execute": true,
    // ... 
}
```

But make sure to wait enough time until all the screenshots are done.

## Optimizations

To take bulk screenshots faster, you can use the optimization feature if you want to take bulk screenshots for the same URLs (HTML or Markdown) but with a different set of parameters: 

```
POST https://api.screenshotone.com/bulk 

{
    "access_key": "<your access key>"
    "execute": true,
    "optimize": true,
    "options": {"url": "https://example.com", "viewport_width": 1280, "viewport_height": 1024}, 
    "requests": [
        {"viewport_width": 360, "viewport_height": 640}, // a screenshot of example.com with a different viewport
        {"viewport_width": 736, "viewport_height": 414}
    ]
}
```

<Alert>
The feature only works when `execute` is set to `true`.
</Alert>

The optimization is not guaranteed since many sites can reload and take the same time to render in case the viewport is changed. And some options, like blocking and not blocking ads, do require a page reload, which takes the same time as not using optimization at all. 

The best approach is to test if it works for your use case.

## Use cases 

### Upload bulk screenshots to S3-compatible storage

In the example, I want to take screenshots for one site but for different devices and upload them to [S3-compatible storage](https://screenshotone.com/docs/options/#storing): 

```
POST https://api.screenshotone.com/bulk 

{
    "access_key": "<your access key>"
    "execute": true,
    "options": {"url": "https://example.com", "store": true, "response_type": "empty"}, 
    "requests": [
        {"viewport_device": "pixel_4a_5g_landscape", "storage_path": "pixel_4a_5g_landscape"},        
        {"viewport_device": "iphone_13_pro", "storage_path": "iphone_13_pro"},        
        {"viewport_device": "iphone_13", "storage_path": "iphone_13"}        
    ]
}
```

In this example, I upload screenshots taken from different devices and save the files with the names of the devices. 

## Limitations

Currently, only up to 20 requests are supported in the one bulk request.

# Animated Screenshots

import Alert from "@/components/Alert.astro";
import Video from "@/components/Video.astro";

<Alert>
    In case you need a custom scenario or have propositions, feel free to reach
    out at `support@screenshotone.com`.
</Alert>

You can rely on ScreenshotOne API to generate animated screenshots and handle image and video streaming infrastructure.

ScreenshotOne supports animated (including scrollable) screenshots of different types, caching based on the world’s fastest and most potent CDN (Cloudflare), blocking ads, cookie banners, and chats.

In just one API request, you can quickly generate animated screenshots. And if you need more, various scenarios with many options are covered.

Grasp how simple it is:

```
https://api.screenshotone.com/animate?url=https://tailwindcss.com&scenario=scroll&access_key=<your access key>
```

The result might differ a bit in case default options are changed, but as for now, it is similar to what I have shown in the video:

<Video url="/videos/animated_screenshot.mp4" />

Don't forget that you can use [signed links to share videos and GIF images publicly](https://screenshotone.com/docs/signed-requests/), [caching](https://screenshotone.com/docs/options/#caching), [block ads](/docs/options/#block_ads), [block cookie banners](/docs/options/#block_cookie_banners), and [many other options](#all-supported-options).

## Scenarios

Select a basic scenario of how you want to animate screenshots or render ed HTML. Specify additional options and tune the scenario for your use case. And you are good to go.

### Default (stand still)

Use the `scenario=default` parameter, or don't specify `scenario` at all when sending a request to `/animate`.

The default scenario is to record animation after loading the site without additional animations.

The use case is when you generate animated screenshots of sites that have animations and you want to showcase it.

Look at [the Handwrytten site](https://www.handwrytten.com/) as an example. It has a default animation when loaded. So, we won't scroll it or add any other activities.

We will record the site as is after load:

```
https://api.screenshotone.com/animate?url=https://www.handwrytten.com/&access_key=<your access key>
```

The result:

<Video url="/videos/animated_handwrytten.mp4" />

### Scrollable (scrolling) screenshot

Use the `scenario=scroll` parameter, or don't specify `scenario` at all when sending a request to `/animate`.

There is an example for scrolling [Senja](https://senja.io):

```
https://api.screenshotone.com/animate?url=https://senja.io&scenario=scroll&access_key=<your access key>
```

The result is:

<Video url="/videos/animated_senja.mp4" />

These are supported options for scrolling screenshot animation:

-   `scroll_delay`—delay in milliseconds between scrolls. The default value is `500`.
-   `scroll_duration`—duration in milliseconds of one scroll. The default value is `1500`. The scroll duration is not the duration of the video or animated GIF. Please, use the `duration` parameter to specify the length of the video or animated GIF.
-   `scroll_by`—by how many pixes scroll. The default value is `1000`.
-   `scroll_start_immediately`—scroll immediately or wait for the `scroll_delay` milliseconds before scrolling. The default value is `true`.
-   `scroll_start_delay`—wait time (in milliseconds) till starting scrolling. The default value is `0``.
-   `scroll_back`—scroll back or not. The default value is `true`.
-   `scroll_back_algorithm`—`once` is by default and means that it will scroll back immediately once with the easing you have defined. But if you set `repeat`, it will repeat the same algorithm the API used to scroll to the bottom of the page.
-   `scroll_back_after_duration`—scroll back after the specified duration in milliseconds.
-   `scroll_complete`—stop recording animation when full scrolling is completed. The option `true` by default.
-   `scroll_stop_after_duration`—stop scrolling after the specified duration in milliseconds. Use `scroll_complete=false` and `scroll_back=false`, to stop and just stand still after the specified duration.
-   `scroll_easing`—use it to define the scrolling easing effect. The default value is `ease_in_out_quint`. There is a list of all available options:
    -   `linear`–no easing, no acceleration;
    -   `ease_in_quad`–accelerating from zero velocity;
    -   `ease_out_quad`–decelerating to zero velocity;
    -   `ease_in_out_quad`–acceleration until halfway, then deceleration;
    -   `ease_in_cubic`–accelerating from zero velocity;
    -   `ease_out_cubic`–decelerating to zero velocity;
    -   `ease_in_out_cubic`–acceleration until halfway, then deceleration;
    -   `ease_in_quart`–accelerating from zero velocity;
    -   `ease_out_quart`–decelerating to zero velocity;
    -   `ease_in_out_quart`–acceleration until halfway, then deceleration;
    -   `ease_in_quint`–accelerating from zero velocity;
    -   `ease_out_quint`–decelerating to zero velocity;
    -   `ease_in_out_quint`–acceleration until halfway, then deceleration.
-   `scroll_try_navigate`—navigate while scrolling and record the new opened page.
-   `scroll_navigate_after`—navigate after duration in milliseconds, by default it is half of the duration.
-   `scroll_navigate_to_url`—to what URL navigate;
-   `scroll_navigate_link_hints`—if the URL is not specified, the hints of what links to use, by default `'pricing', 'about', 'customers'`.  E.g. "pricing" means to open any internal link which has the "pricing" keyword in its text;
-   `scroll_till_selector`—scroll till the selector is visible;
-   `scroll_till_selector_adjust_top`—adjust the top position of the selector in the viewport;
-   `scroll_to_end_after`—scroll to the end after the specified duration in milliseconds with the specified easing in one scroll.

There is an example of applying custom options for scrolling [Senja](https://senja.io):

```
https://api.screenshotone.com/animate?url=https://senja.io&scenario=scroll&scroll_delay=400&scroll_by=400&access_key=<your access key>
```

The result is:

<Video url="/videos/animated_senja_custom.mp4" />

### Navigation

You can record a page navigation when recording scrolling screenshot video. It allows render less boring and more engaging videos.

<Video url="/videos/scrolling_screenshot_navigation.mp4" />

It is rendered with a simple request like: 

```
https://api.screenshotone.com/animate?url=https://screenshotone.com/&scenario=scroll&duration=10&scroll_try_navigate=true&scroll_navigate_link_hints=pricing&access_key=<YOUR KEY>
```

You need to specify either the "scroll_navigate_to_url" or the "scroll_navigate_link_hints" options.
If neither is specified, any first random visible internal link will be used for navigation if available.

The `scroll_navigate_link_hints` option can be used as an array:

```
scroll_navigate_link_hints[]=pricing&scroll_navigate_link_hints[]=about
```

The API will attempt to find any internal links that match the hints.

## All supported options

### Animation specific

#### format

Available response formats:

-   `mp4`
-   `mov`
-   `avi`
-   `webm`
-   `gif`

Default value is `mp4`.

#### duration

<Alert>
    If you need a longer animation, please, reach out at
    `support@screenshotone.com` and describe your use case.
</Alert>

The default value is `5` seconds (`duration=5`).

The minimum value is `1` and the maximum is `30`.

Suppose `scroll_complete` is set to `true`, which is by default, and [the scrolling scenario](/docs/animated-screenshots/#scrollable-scrolling-screenshot)) is completed earlier than the specified `duration`. In that case, the recording will be stopped, and the resulting animation will be short.

Since GIFs are not videos, but images, the duration might not be mapped exactly to the number of frames and represent the duration as is for the video. It is better to consider it as a duration of recording of the video, and then frames glued together into a GIF. 

#### width

You must specify both the `width` and [height](#height) parameters. You can't specify only one. By default, the width and the height parameters are the same as [viewport width](/docs/options/#viewport_width) and [viewport height](/docs/options/#viewport_height) parameters.

[The device scale factor](/docs/options/#device_scale_factor) is taken into consideration. If you set the viewport width and height to `1000x500`, with `device_scale_factor=1`, the resulting resolution of the video will be `1000x500`, but with `device_scale_factor=2`, it will be `2000x1000`.

If [aspect ratio](#aspect_ratio) is specified, `width` and `height` are not used. And API will try to fit the video of the viewport size into the specified aspect ratio.

#### height

You must specify both the [width](#width) and `height` parameters. You can't specify only one. By default, the width and the height parameters are the same as [viewport width](/docs/options/#viewport_width) and [viewport height](/docs/options/#viewport_height) parameters.

[The device scale factor](/docs/options/#device_scale_factor) is taken into consideration. If you set the viewport width and height to `1000x500`, with `device_scale_factor=1`, the resulting resolution of the video will be `1000x500`, but with `device_scale_factor=2`, it will be `2000x1000`.

If [aspect ratio](#aspect_ratio) is specified, `width` and `height` are not used. And API will try to fit the video of the viewport size into the specified aspect ratio.

#### aspect ratio

If [aspect ratio](#aspect_ratio) is specified, `width` and `height` are not used. And API will try to fit the video of the viewport size into the specified aspect ratio.

#### scenario

Available scenarios formats:

-   not specified or `default` is for [the default animation scenario](#default-stand-still).
-   `scroll` is for [the scrolling screenshots](#scrollable-scrolling-screenshot).

The default value is `default`.

#### clip

You can clip part of the video. But currently, it is only available when the format is `gif`.

Use `clip_width`, `clip_height, `clip_x`and`clip_y` to specify the clip size and coordinates.

### Regular

Animated screenshots also support most options supported by regular image screenshots. There is a list of supported options:

-   `omit_background` but only for the `mov` format;
-   [credentials](/docs/options/#credentials);
-   [essentials](/docs/options/#essentials), except `selector` and with different values for [format](#format);
-   [viewport](/docs/options/#viewport);
-   [emulations](/docs/options/#emulations);
-   [customization](/docs/options/#customization);
-   [blocking](/docs/options/#blocking);
-   [geolocation](/docs/options/#geolocation);
-   [request](/docs/options/#request);
-   [wait](/docs/options/#wait);
-   [caching](/docs/options/#caching);
-   [storing](/docs/options/#storing).

# Async and Webhooks

import Alert from "@/components/Alert.astro";

ScreenshotOne supports asynchronous screenshot rendering and webhooks. The document describes both of them in one
place since usually they are used together.

The main current supported use case is to render screenshots asynchronously, [upload them to S3](/docs/upload-to-s3/) and return the file location to the specified webhook. That's what customers asked to implement first.

## Async

You can literally execute any request asynchronously by setting the `async` option to `true.` But not every request makes sense to execute asynchronously.

Once you set `async=true,` the API checks your access key and limits and returns the response immediately but continues to execute the request.

One of the top use cases for which it was requested is uploading files to S3 asynchronously without waiting for screenshots to be rendered.

An example of such a request could be:

```
https://api.screenshotone.com/take?access_key=0MpjJxw8Vk7ZAw&url=https://example.com&store=true&storage_path=example.com&response_type=json&async=true
```

You request rendering but don't wait for the response. What if you want to get the result of uploading? You can do it by using webhooks.

## Webhooks

Using webhooks with ScreenshotOne allows you to deliver the results of the request execution to your URL as a POST body.

<Alert>
    Currently, caching is not supported for webhooks since it doesn't make much
    sense. If you need its support for other use cases, please, send a chat
    message or email to `support@screenshotone.com`.
</Alert>

You can use webhooks with both synchronous and asynchronous requests. But usually, it is used in combination with asynchronous requests.

An example of an asynchronous request that uploads rendered screenshot to S3 and sends a webhook might look like this:

```
https://api.screenshotone.com/take?access_key=<your api key>
  &url=https://example.com
  &store=true
  &storage_path=example.com
  &response_type=json
  &async=true  
  &webhook_url=<your webhook URL>
  &storage_return_location=true
```

Not that, to get the location, you must specify the `storage_return_location` parameter as `true`.

An example of the webhook request body you will receive:

```
{
  "screenshot_url": "...",
  // ...
  "store": {
    // ...
    "location": "..."
  },
}
```

You also receive the `X-ScreenshotOne-Signature` (`x-screenshotone-signature`) header that you should use to validate the webhook request body and make sure that ScreenshotOne sent the request.

If you do not upload the screenshot to any S3-compatible storage, you will receive [the `screenshot_url`](/docs/screenshot-url/) in the response body if you set `response_type=json`: 

```json
{
  // ...
  "screenshot_url": "..."
}
```

If you don't specify the `response_type` parameter as `json`, you will receive the screenshot in the binary format in the response body.

```
<binary data>
```

### Verifying Signature

To ensure that ScreenshotOne sent the request, you should get the signature from the `X-ScreenshotOne-Signature` header and verify it with your secret key from [the access page](https://dash.screenshotone.com/access) by applying the HMAC SHA-256 algorithm.

<Alert>
    Never share your secret key with any party. In case it is leaked, you can
    quickly regenerate it on [the access
    page](https://dash.screenshotone.com/access).
</Alert>

A pseudo-code on TypeScript (Node.js) of how you can do it:

```javascript
import * as crypto from "crypto";

const receivedSignature = request.headers.get("x-screenshotone-signature");
const requestBody = await request.rawText();

const calculatedSignature = crypto
    .createHmac("sha256", yourSecretKey)
    .update(requestBody, "utf-8")
    .digest("hex");

if (calculatedSignature !== receivedSignature) {
    // the signature is not valid
    // you should not process this request and reject it immediately
    throw new Error("...");
}

// it is safe to process the request
// you can do something with the webhook request body
```

### Disable Signing

Singing webhook request body takes time. If you are sure that your webhooks are unique and secret, you might want to disable signing to improve performance by using `webhook_sign=false`.

### Debugging and support headers

There are a few headers that are not part of the body and are not participating in the signing. They must not be used for any logic; it is just for debugging and support purposes:

-   `x-screenshotone-rendering-seconds`—screenshot rendering time in seconds with fractions, e.g. `2.56`;
-   `x-screenshotone-size-bytes`—screenshot size if available (not streaming), e.g. `30033`;
-   `x-screenshotone-trace-id`—unique request trace id when reaching out to the ScreenshotOne support;
-   `x-screenshotone-reference`—screenshot or video id (if available) that can be seen in the history or used when reaching out to the ScreenshotOne support.

### External identifier

You can set `external_identifier` parameter to any alphanumeric value. It will be included in the webhook request headers:

- `x-screenshotone-external-identifier`—external identifier. It is helpful for error tracking and successful request tracking.

### Webhook errors

We currently don't support a separate endpoint to send webhook errors. But you can still get them in the webhook request body or headers.

By default, errors are not sent to the webhook URL, at all. But if you want to get them, you can set `webhook_errors=true` parameter.

And you will get error details in the webhook request body if the JSON response type is used: 

```javascript
{
    // ...  
    "error_code": "...",
    "error_message": "...",
    "documentation_url": "..."
}
```

Or always in the headers: 

- `x-screenshotone-error-code`—error code;
- `x-screenshotone-error-message`—error message;
- `x-screenshotone-documentation-url`—documentation URL about the error.

Check out all possible error codes in the [API error reference](/docs/errors/).

### Testing webhook errors

You can test it with an URL like this `https://example.com/404`. It will trigger an error.

In general, it is enough to check for the error code presence or absence of the screenshot URL/binary data to determine if the request was successful or not.

In the worst case scenario, you might assume if you haven't been notified about any errors or successful requests, likely the request has been failed.

## Summary

That's it. In case you have any questions or problems, feel free to write to `support@screenshotone.com`.

# Errors

import Alert from "@/components/Alert.astro";

<Alert>
    There is [a detailed guide](/docs/guides/how-to-handle-api-errors/) on how
    to handle the ScreenshotOne API errors.
</Alert>

The request might return an error due to an internal error, invalid options or when the limit is reached. Our screenshot API follows the HTTP status code semantic and returns JSON in case of an error:

```
GET https://api.screenshotone.com/?[options]

Content-Type: application/json
{
    "is_successful": false,
    "error_code": "an_error_code",
    "error_message": "An error message",
    "documentation_url": "..."
}
```

The API will always return a human-readable error message, error code as a string key, and suitable HTTP status code.

## Codes with explanations

| Error Code                                                             | HTTP Status | Explanation                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [access_key_required](/docs/errors/access-key-required/)                                                    | 400         | The "access_key" parameter is required. Please, check out [the access page](https://dash.screenshotone.com/access) to get the access key.                                                                                                                                                                                                                   |
| [access_key_invalid](/docs/errors/access-key-invalid/)                                                     | 400         | The "access_key" parameter is given, but it is not correct. Please, check out [the access page](https://dash.screenshotone.com/access) to check the access key.                                                                                                                                                                                             |
| [signature_is_required](/docs/errors/signature-is-required/)                                                  | 400         | The "signature" parameter is required. Because signing requests is required in [the access page](https://dash.screenshotone.com/access). Make sure you use [the correct signing algorithm](/docs/signed-requests/).                                                                                                                                         |
| [signature_is_not_valid](/docs/errors/signature-is-invalid/)                                                 | 400         | You provided the "signature" parameter, but it is not valid. Make sure you use [the correct signing algorithm](/docs/signed-requests/).                                                                                                                                                                                                                     |
| [screenshots_limit_reached](/docs/errors/usage-quota-exceeded/)        | 400         | The usage quota has been exceeded. Please, either upgrade to a plan with more quota or change the maximum allowed limit (if possible) in the ScreenshotOne dashboard. If it is a mistake, please, reach out at `support@screenshotone.com.`                                                                                                                 |
| [concurrency_limit_reached](/docs/errors/concurrency-limit-reached/)                                              | 400         | You reached the request concurrency limit, retry after a while. Or feel free to [upgrade you current plan](https://dash.screenshotone.com/subscription).                                                                                                                                                                                                    |
| [request_not_valid](/docs/errors/request-invalid/)                                                      | 400         | The request parameters are not valid. You can look at the `error_details` response field to get the details.                                                                                                                                                                                                                                                |
| [selector_not_found](/docs/errors/selector-not-found/)                                                     | 400         | If [selector](/docs/options#selector) is specified and `error_on_selector_not_found=true`, the error will be returned if the element by selector is not visible or it took more than `timeout` seconds to render it, but not more than 30 seconds.                                                                                                          |
| [name_not_resolved](/docs/errors/name-not-resolved/)                                                      | 400         | Usually, the error happens when the domain name of the requested URL is not resolved. If you are trying to take a screenshot of the new site, please, wait a bit until the DNS records are refreshed.                                                                                                                                                       |
| [network_error](/docs/errors/network-error/)                                                          | 500         | The error happens when the API can't connect to the provided URL. It might mean that the site blocks the API or is temporarily unavailable. Generally, you can safely retry to take a screenshot.                                                                                                                                                           |
| [invalid_storage_configuration](/docs/errors/invalid-storage-configuration/)                                          | 400         | If you haven't created the bucket in the `us-east-1` AWS region, please, specify your bucket region through an endpoint in a format like `https://s3.<your-region>.amazonaws.com`.                                                                                                                                                                          |
| [script_triggers_redirect](/docs/errors/script-triggers-redirect/)     | 400         | The specified "scripts" option might trigger a redirect, please, specify the "scripts_wait_until" option. If you think it is a mistake, please, reach out at `support@screenshotone.com`.                                                                                                                                                                   |
| [host_returned_error](/docs/errors/host-returned-error/)                                                    | 500         | If the host doesn't respond successfully within the range of 200-299 status codes, the API won't take a screenshot. You can force the API to take a screenshot of the error page by specifying [ignore_host_errors=true](/docs/options#ignore_host_errors). You can get the returned status code from the site by reading the `returned_status_code` field. |
| [timeout_error](/docs/errors/timeout/)                                 | 500         | The screenshot couldn't be taken within the specified timeout. Either the site doesn't respond quickly, or rendering takes longer than expected. Play with the `timeout` or the `navigation_timeout` options or reach the support for the investigation.                                                                                                    |
| [internal_application_error](/docs/errors/internal-application-error/) | 500         | The API failed to serve your request. You can safely replay the request. We are notified about it instantly and will try to fix it as soon as possible. If the error is repeated for a long time, feel free to reach out at support@screenshotone.com.                                                                                                      |
| [storage_access_denied](/docs/errors/storage-access-denied/)           | 400         | Failed to upload the screenshot to the storage since access was denied. Check the API keys you specify when using the storage integration.                                                                                                                                                                                                                  |
| [storage_returned_transient_error](/docs/errors/storage-returned-transient-error/)                                       | 500         | The storage returned an HTTP status code between 500 and 599 and we exhausted retries. You can likely retry the request again.                                                                                                                                                                                                                              |
| [request_aborted](/docs/errors/request-aborted/)                       | 500         | The request was aborted either by the user or the intermediate proxies and can't be fulfilled. If the error persists, please, reach out to support@screenshotone.com.                                                                                                                                                                                       |
| [content_contains_specified_string](/docs/errors/content-contains-specified-string/)                                      | 500         | The page content contains the specified string by the [fail_if_content_contains](/docs/options#fail_if_content_contains) option. If it seems to be a mistake or not what you expected, please, reach out to \`support@screenshotone.com\` as quickly as possible, and will assist and try to resolve your problem.                                          |
| [temporary_unavailable](/docs/errors/temporary-unavailable/)                                                  | 503         | The API is temporarily unavailable due to an error or overload. Please wait a bit and then safely retry your request.                                                                                                                                                                                                                                       |
| [invalid_cookie_parameter](/docs/errors/invalid-cookie-parameter/)                                                  | 400         | The `cookies` parameters you provided are invalid. Please, consider providing different values and adhere to the format specified in the ScreenshotOne documentation.                                                                                                                                                                                                                                       | 
| [resulting_image_too_large](/docs/errors/resulting-image-too-large/)                                                  | 400         | The resulting image is too large for the specified format. Please, consider providing different values and adhere to the format specified in the ScreenshotOne documentation.                                                                                                                                                                                                                                       | 
| [matched_failed_request](/docs/errors/matched-failed-request/)                                                  | 500         | The request matched by the specified pattern by the [fail_if_request_failed](/docs/options#fail_if_request_failed) option has been failed. If it seems to be a mistake or not what you expected, please, reach out to \`support@screenshotone.com\` as quickly as possible, and will assist and try to resolve your problem.                                          | 
| [invalid_header_parameter](/docs/errors/invalid-header-parameter/)                                                  | 400         | The `headers` parameters you provided are invalid. Please, consider providing different values and adhere to the format specified in the ScreenshotOne documentation.                                                                                                                                                                                                                                       | 
| [request_body_too_large](/docs/errors/request-body-too-large/)                                                  | 413         | The request body is too large. Please, reduce the size of the request body or reach out to \`support@screenshotone.com\` for assistance.                                                                                                                                                                                                                                       | 

## List of all errors

1. [Timeout error](/docs/errors/timeout/).
2. [Storage Access Denied](/docs/errors/storage-access-denied/).
3. [Script Trigger Redirect](/docs/errors/script-triggers-redirect/).
4. [Internal Application Error](/docs/errors/internal-application-error/).
5. [Usage Quota Exceeded](/docs/errors/usage-quota-exceeded/).
6. [Request Aborted](/docs/errors/request-aborted/).
7. [Access Key Required](/docs/errors/access-key-required/).
8. [Access Key Invalid](/docs/errors/access-key-invalid/).
9. [Signature Is Required](/docs/errors/signature-is-required/).
10. [Signature Is Not Valid](/docs/errors/signature-is-invalid/).
11. [Screenshots Limit Reached](/docs/errors/usage-quota-exceeded/).
12. [Concurrency Limit Reached](/docs/errors/concurrency-limit-reached/).
13. [Request Not Valid](/docs/errors/request-invalid/).
14. [Selector Not Found](/docs/errors/selector-not-found/).
15. [Name Not Resolved](/docs/errors/name-not-resolved/).
16. [Network Error](/docs/errors/network-error/).
17. [Invalid Storage Configuration](/docs/errors/invalid-storage-configuration/).
18. [Host Returned Error](/docs/errors/host-returned-error/).
19. [Storage Returned Transient Error](/docs/errors/storage-returned-transient-error/).
20. [Content Contains Specified String](/docs/errors/content-contains-specified-string/).
21. [Temporary Unavailable](/docs/errors/temporary-unavailable/).
22. [Invalid Cookie Parameter](/docs/errors/invalid-cookie-parameter/).
23. [Resulting Image Too Large](/docs/errors/resulting-image-too-large/).
24. [Matched Failed Request](/docs/errors/matched-failed-request/).
25. [Invalid Header Parameter](/docs/errors/invalid-header-parameter/).
26. [Request Body Too Large](/docs/errors/request-body-too-large/).

# ScreenshotOne IP Ranges

In case you need to allow access from the ScreenshotOne API to your servers or your proxy provider allow list, you can configure your firewall to allow the following IP addresses:

1. IPs for the `east-4` region [from public Google Cloud IP ranges](https://www.gstatic.com/ipranges/cloud.json).
2. Hetzner GPU rendering IP (if applicable for your use case)—`95.216.67.59`.
3. IP range for New York from [DigitalOcean Public IPs](https://digitalocean.com/geo/google.csv).

If that doesn't work for you, please, reach out at `support@screenshotone.com` with any questions you have and we will try to get back to you as soon as possible.

# Signed Links

import Alert from "@/components/Alert.astro";

When you share links to the screenshots with your access key in public, there is a problem that everybody can take your API access key and reuse it to take screenshots on their own and exhaust your screenshot quota.

To prevent others from using your API key, you need to:
1. [Sign every request](https://screenshotone.com/docs/signed-requests/#signing-requests) you are going to share publicly.
2. [Require signing](https://screenshotone.com/docs/signed-requests/#require-signing) for every request.

Then even if the potential unscrupulous person sees or steals your access key, they can't reuse it until they also steal your secret key (signing key).

You generally don't need to sign requests if you will not share screenshot links publicly and will use screenshot API only on the server-side.

## Signing requests

<Alert>
Singed links do not work with HTTP "POST" requests. The feature is intended to be used for sharing links in public.
</Alert>

To sign the request, like `https://api.screenshotone.com/take?access_key=0Ij4LFMtFnGUrA&url=https://apple.com`, you need to follow the simple algorithm:

1. Use your secret to hash the query string `access_key=0Ij4LFMtFnGUrA&url=https://apple.com` with the HMAC SHA256 algorithm.
  
2. **Append** the signature parameter with the hash: `https://api.screenshotone.com/?access_key=0Ij4LFMtFnGUrA&url=https://apple.com&signature=70bea3e52efc43834129ecbea236f38bf9bb4a7cd7c2e1951017435defd4dbaf`.

**Do not sort the parameters. Or if you sort them, send them sorted, too.**
  
To hash the query string with your secret key and HMAC SHA256 algorithm in the CLI, you can run the following command:

```bash
$ echo -n "access_key=0Ij4LFMtFnGUrA&url=https://apple.com" | openssl sha256 -hmac "m9ajW9br9hTw2A"                     130 ↵

70bea3e52efc43834129ecbea236f38bf9bb4a7cd7c2e1951017435defd4dbaf
```

## Code examples

You can need to apply the same algorithm in the language of your choice.

### Python

For example, in Python:

```python
import urllib.parse
import hmac
import hashlib

def generate_signature(params: dict, secret_key: str) -> str:
    """
    Generate a signature for the given parameters using HMAC-SHA256.
    
    Args:
        params (dict): Dictionary of parameters to sign
        secret_key (str): Secret key used for signing
        
    Returns:
        str: The hexadecimal signature
    """        
    # convert parameters to URL-encoded query string
    query_string = urllib.parse.urlencode(params, doseq=True)

    signature = hmac.new(
        bytes(secret_key, "utf-8"),
        msg=bytes(query_string, "utf-8"),
        digestmod=hashlib.sha256,
    ).hexdigest()
    
    return signature

# Example usage
if __name__ == "__main__":
    # options
    params = {
        "access_key": "your_access_key",
        "url": "https://example.com",
        "format": "jpeg",
        "viewport_width": 1920,
        "viewport_height": 1080
    }
    
    secret_key = "your_secret_key"
    
    # generate signature
    signature = generate_signature(params, secret_key)
    
    print("Parameters:", params)
    print("Query string:", urllib.parse.urlencode(params, doseq=True))
    print("Signature:", signature)
    
    query_string = urllib.parse.urlencode(params, doseq=True)
    final_url = f"https://api.screenshotone.com/take?{query_string}&signature={signature}"
    print("\nAPI URL:", final_url)
```

### JavaScript

Or in JavaScript:

```javascript
// npm install @peculiar/webcrypto
import { Crypto } from "@peculiar/webcrypto";

const encoder = new TextEncoder();

export async function signQueryString(queryString: string, secretKey: string) {
    const webCrypto =
        typeof globalThis.crypto !== "undefined"
            ? globalThis.crypto
            : new Crypto();

    let algorithm = { name: "HMAC", hash: "SHA-256" };
    let key = await webCrypto.subtle.importKey(
        "raw",
        encoder.encode(secretKey),
        algorithm,
        false,
        ["sign", "verify"]
    );
    const digest = await webCrypto.subtle.sign(
        algorithm.name,
        key,
        encoder.encode(queryString)
    );

    const signature = Array.from(new Uint8Array(digest))
        .map((b) => b.toString(16).padStart(2, "0"))
        .join("");

    return signature;
}

// example usage
const query = new URLSearchParams({
    access_key: "your_access_key",
    url: "https://example.com"
});
let queryString = query.toString();

const signature = await signQueryString(queryString, "your_secret_key");
queryString += "&signature=" + signature;

console.log(queryString);
```

## Require signing

After you start signing requests and make sure that the API accepts your requests, you can require signing every request.
Go to [the access configuration page](https://dash.screenshotone.com/access) and enforce signing every request.
The change will be applied immediately, but cached screenshots might not be impacted.
That's it. After this step, unsigned requests with your API access key are not accepted.

## Animated screenshots 

[Animated screenshots](/docs/animated-screenshots/) also support signed links. There is no difference in the underlying mechanism besides that the URL prefix should be `/animate`.

# Devices

import Alert from "@/components/Alert.astro";
import devices from "screenshotone-devices";

Instead of manually specifying viewport parameters like width and height, you can specify a device to use for emulation. In addition, other parameters of the viewport, including the user agent, will be set automatically. 

The [viewport_device](/docs/options/#viewport_device) option sets the next options for you: [viewport_width](/docs/options/#viewport_width), [viewport_height](/docs/options/#viewport_height), [device_scale_factor](/docs/options/#device_scale_factor), [viewport_mobile](/docs/options/#viewport_mobile), [viewport_has_touch](/docs/options/#viewport_has_touch), [viewport_landscape](/docs/options/#viewport_landscape). You can change these options and override the ones set by the `viewport_device` option. 

<Alert>
API does not use an actual device to take a screenshot. It is emulation that works in most cases. 
</Alert>

Use the `id` property of the device as the [viewport_device](/docs/options/#viewport_device) option, e.g. `viewport_device=galaxy_s9+_landscape`.

You can get the list of supported devices by:

```
GET https://api.screenshotone.com/devices?access_key=<YOUR ACCESS KEY>`

[
    {
        "id": "iphone_13_pro_max_landscape",
        "name": "iPhone 13 Pro Max landscape",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.4 Mobile/15E148 Safari/604.1",
        "viewport": {
            "width": 926,
            "height": 428,
            "deviceScaleFactor": 3,
            "isMobile": true,
            "hasTouch": true,
            "isLandscape": true
        }
    },
    // ... many devices ... 
    {
        "id": "galaxy_s9+",
        "name": "Galaxy S9+",
        "userAgent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G965U Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.111 Mobile Safari/537.36",
        "viewport": {
            "width": 320,
            "height": 658,
            "deviceScaleFactor": 4.5,
            "isMobile": true,
            "hasTouch": true,
            "isLandscape": false
        }
    },
    {
        "id": "galaxy_s9+_landscape",
        "name": "Galaxy S9+ landscape",
        "userAgent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G965U Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.111 Mobile Safari/537.36",
        "viewport": {
            "width": 658,
            "height": 320,
            "deviceScaleFactor": 4.5,
            "isMobile": true,
            "hasTouch": true,
            "isLandscape": true
        }
    }, 
    // ... many devices ... 
]
```

## Devices

The list of devices returned by API is dynamic and continuously updated. But there is a snapshot of all supported devices if you want to take a quick look (**don't rely on it solely, use the API method** `GET /devices` **instead**): 


<table class="table-sm table-sm mt-2 mb-4">
    <thead>
        <tr>
            <th rowspan="2" class="text-center">Device (id)</th>
            <th class="text-center">Viewport (scale)</th>
            <th class="text-center">Mobile</th>
            <th class="text-center">Touch</th>
            <th class="text-center">Landscape</th>
        </tr>
        <tr>
            <th colspan="5" class="text-center">User Agent</th>
        </tr>
    </thead>
    <tbody>
        {Object.entries(devices.default.devices).map(([id, device]) => (
            <>
            <tr class="text-sm">
                <td rowspan="2" class="text-center small">{device.name} ({id})</td>
                <td class="text-center">{device.viewport.width}x{device.viewport.height} ({device.viewport.deviceScaleFactor})</td>
                <td class="text-center">
                    {device.viewport.isMobile ? "Yes" : "No"}
                </td>
                <td class="text-center">
                    {device.viewport.hasTouch ? "Yes" : "No"}
                </td>
                <td class="text-center">
                    {device.viewport.isLandscape ? "Yes" : "No"}
                </td>               
            </tr>
            <tr class="text-sm">
                <td colspan="5" class="text-center">{device.userAgent}</td>
            </tr>
            </>
        ))}

</tbody>    
</table>

# Screenshot URL

:::danger
The URL is temporary and will be available for a limited time—**4 hours maximum**. Do not rely on it for long-term storage of screenshots.

Except, when you use [caching](/docs/caching/), and the cache TTL is set to more than 4 hours.
:::

:::note
For long-term screenshot or video archival, consider [uploading them to any compatible S3-storage](/docs/guides/upload-to-s3/).
:::


When you set `response_type=json` for both [animated/scrolling screenshots](/docs/animated-screenshots/) or [regular screenshots](/docs/options/), you will get a screenshot URL in the response:

```json
{
    "screenshot_url": "..."
}
```

The URL is always a fresh URL where the screenshot is stored, it is not a cached URL unless you use [caching](/docs/caching/).

Also, when [using webhooks](/docs/async-and-webhooks/) and if you do not upload the screenshot to any S3-compatible storage, you will get the URL in the webhook request body,too.

# Get Usage

You can get your current plan usage by:

```
GET https://api.screenshotone.com/usage?access_key=<YOUR ACCESS KEY>`

{
    "total": 10000, 
    "available: 950, 
    "used": 9050,
    "concurrency": {
        "limit":20,
        "remaining":20,
        "reset":1681646947775437264
    }
}
```

A bit of clarification: 

- `total` is the total number of requests allowed in the current billing plan period;
- `available` is the number of available requests until the end of the current period;
- `used` is the number of successfully executed requests.
- `concurrency.limit` is the total number of concurrent requests allowed per interval;
- `concurrency.remaining` is the number of available concurrent requests allowed per interval;
- `concurrency.reset` is the time when the limitation will be reset, in UNIX timestamp format in nanoseconds.

# Access Key Invalid

It is an API error returned when the provided access key is invalid or incorrect.

```json
{
    "is_successful": false,
    "error_code": "access_key_invalid",
    "error_message": "The `access_key` parameter is set, but it is not correct. Please, check out the access dashboard page to get the access key—https://dash.screenshotone.com/access.",
    "documentation_url": "https://screenshotone.com/docs/errors/access-key-invalid/"
}
```

## Reasons and how to fix

### Incorrect Access Key

One common reason for the "access_key_invalid" error is using an incorrect access key. This can happen if the key is copied incorrectly or if an old key is being used.

To fix this, ensure you are using the correct access key by visiting the [access dashboard page](https://dash.screenshotone.com/access) and copying the key directly from there.

### Typographical Errors

Typos in the access key parameter can also lead to this error. This includes extra spaces, missing characters, or incorrect case sensitivity.

To fix this, carefully check and re-enter the access key, ensuring there are no typographical errors. Copy-pasting the key directly from the dashboard is recommended.

### Misconfigured Environment

In some cases, the environment where the API request is being made might be misconfigured, leading to the wrong access key being used.

To fix this, review your environment configuration settings to ensure the correct access key is being used in the appropriate environment (e.g., development, staging, production).

## Reach out to support

If you continue to face issues, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Access Key Required

It is an API error returned when the access key parameter is missing in the request.

```json
{
    "is_successful": false,
    "error_code": "access_key_required",
    "error_message": "The `access_key` parameter is required. Please, check out the access dashboard page to get the access key—https://dash.screenshotone.com/access.",
    "documentation_url": "https://screenshotone.com/docs/errors/access-key-required/"
}
```

## Reasons and how to fix

### Missing Access Key Parameter

The most common reason for the "access_key_required" error is that the `access_key` parameter is not included in the request. This is mandatory for authenticating and authorizing the API request.

To fix this, ensure that you include the `access_key` parameter in your API request. You can obtain your access key from the [access dashboard page](https://dash.screenshotone.com/access).

### Misconfigured Request

Sometimes, a request might be misconfigured, leading to the `access_key` parameter being omitted.

To fix this, review the configuration of your API client or the code that constructs the request to ensure that the `access_key` parameter is always included.

### Typographical Errors

A typo or incorrect parameter name might lead to the `access_key` not being recognized by the API.

To fix this, double-check the parameter name in your request to ensure it is spelled correctly as `access_key`.

### Programmatic Issues

If you are dynamically generating requests (e.g., through a script or application), there might be a bug causing the `access_key` to be omitted.

To fix this, debug your script or application to ensure the `access_key` is being properly set and included in every API request.

## Reach out to support

If you continue to face issues, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Content Contains Specified String

It is an API error returned when the page content contains a specified string that triggers a failure condition.

```json
{
    "is_successful": false,
    "error_code": "content_contains_specified_string",
    "error_message": "The page content contains the specified string by the `fail_if_content_contains` option. If it seems to be a mistake or not what you expected, please, reach out to `support@screenshotone.com` as quickly as possible, and we will assist and try to resolve your problem.",
    "documentation_url": "https://screenshotone.com/docs/errors/content-contains-specified-string/"
}
```

The page content contains the specified string by the `fail_if_content_contains` option. If it seems to be a mistake or not what you expected, please, reach out to `support@screenshotone.com` as quickly as possible, and we will assist and try to resolve your problem.

# Concurrency Limit Reached

It is an API error returned when the request concurrency limit has been reached.

```json
{
    "is_successful": false,
    "error_code": "concurrency_limit_reached",
    "error_message": "You reached the request concurrency limit, retry after a while. Or feel free to upgrade your current plan—https://dash.screenshotone.com/subscription.",
    "documentation_url": "https://screenshotone.com/docs/errors/concurrency-limit-reached/"
}
```

## Reasons and how to fix

### Exceeded Concurrency Limit

The most common reason for the "concurrency_limit_reached" error is that you have reached the maximum number of concurrent requests allowed by your current subscription plan.

To fix this, you can:

1. **Wait and retry**: Wait for some of the current requests to complete and then retry your request.
2. **Upgrade your plan**: Visit the [subscription page](https://dash.screenshotone.com/subscription) to upgrade your plan, which will increase your concurrency limit.

### High Traffic Periods

During high traffic periods, you might hit the concurrency limit more frequently if multiple requests are being made simultaneously.

To fix this, consider:

1. **Load balancing**: Implementing load balancing strategies to distribute requests more evenly over time.
2. **Queueing requests**: Queueing requests and processing them in batches to avoid hitting the concurrency limit.

### Inefficient Request Handling

If your application is not handling requests efficiently, it might lead to a buildup of concurrent requests, hitting the limit.

To fix this, review your application’s request handling logic to ensure that requests are being processed and completed as efficiently as possible.

## Reach out to support

If you continue to face issues, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Content Missing Specified String

It is an API error returned when the page content is missing a specified string that triggers a failure condition.

```json
{
    "is_successful": false,
    "error_code": "content_missing_specified_string",
    "error_message": "The page content is missing the specified string by the `fail_if_content_missing` option. If it seems to be a mistake or not what you expected, please, reach out to `support@screenshotone.com` as quickly as possible, and we will assist and try to resolve your problem.",
    "documentation_url": "https://screenshotone.com/docs/errors/content-missing-specified-string/"
}
```

The page content is missing the specified string by the `fail_if_content_missing` option. If it seems to be a mistake or not what you expected, please, reach out to `support@screenshotone.com` as quickly as possible, and we will assist and try to resolve your problem.

# Internal Application Error

It is an API error returned when the API fails to serve the request due to internal reasons:

```json
{
    "is_successful": false,
    "error_message": "The API failed to serve your request. You can try replay the request. If the error is repeated after a few retries, please, reach out at `support@screenshotone.com.`",
    "error_code": "internal_application_error",
    "documentation_url": "https://screenshotone.com/docs/errors/internal-application-error/"
}
```

## Retry

On rare occasions it can be caused by the website you try to screenshot. So, you can retry the request. It is free, ScreenshotOne doesn't charge you for retries and cached requests.

## Reach out to support

Most of the time, the error is triggered because of some issues in the API or even because of some bugs.

If nothing helps you, please, reach out to `support@screenshotone.com` and we will try to help you as fast as possible.

# Caching

:::note
**Screenshots are not cached by default.**

Caching is free and available for all plans. However, it is not intended to be used in CDN-like scenarios. It is for you to save costs on rendering.
:::

To use cache, the only option you need to set is `cache=true`:

```
https://api.screenshotone.com/screenshot?url=https://example.com&cache=true
```

[Check out more cache options](/docs/options/#caching).

And the screenshot will be cached for 4 hours by default or if you specify the `cache_ttl` option in seconds, you can prolong the cache time up to one month.

Caching is available for all rendering methods.

## When to use cache

The best usage of cache is to make rendering less expensive and faster, in case if you plan to render a lot of similar websites.

## Cache key

Screenshots are cached by the combination of all specified request options. And the [cache_key](/docs/options/#cache_key) option allows having different cached versions of the same screenshot.

## Impact on rendering quota

Cached screenshots are not counted by quota and are not logged anywhere. They are served directly from the cache. Screenshots are cached in a combination of Cloudflare CDN and R2 storage (like Amazon S3).

However, rarely but cache misses might happen and screenshots might be rendered again and counted towards your quota.

## Cache URL

:::note
Fetching the cache URL doesn't trigger the rendering process. It is a direct link to the cached screenshot.

If you want to regenerate the cache, you need to make a new API request with the same parameters and if the cache is expired, it will be rendered again.
:::

There is a header `x-screenshotone-cache-url` that provides a direct link to the cached image, PDF or video. The file exist as long as it was defined in the [cache_ttl](/docs/options/#cache_key) parameter when API request was performed with `cache=true`.

And if the `response_type` option is specified as `json`, you can find a cache URL in the JSON response too:

```json
{
    "cache_url": "https://cache.screenshotone.com/..."
}
```

What is the benefits of using the cache URL?

1. You don't share API keys and don't complicate your code with [signed links](/docs/signed-requests/).
2. You have full control over when the cache is refreshed—only you can trigger cache regeneration by making a new API request with the same parameters. If you share just the cache URL, others can only access the cached screenshot and cannot cause it to be regenerated after it expires. In contrast, sharing an API request link would allow anyone to trigger a new rendering once the cache expires. **Important!** The link will be unavailable after the cache is expired.

[The screenshot URL](/docs/screenshot-url/) might be different from the cache URL, but it will be likely the same as the cache URL.

## Cache TTL

:::note
For long-term screenshot or video archival, consider [uploading them to any compatible S3-storage](/docs/guides/upload-to-s3/).
:::

The cache TTL is 4 hours by default. You can change it by specifying the `cache_ttl` option in seconds up to one month.

Once the cache TTL is reached, the cached screenshot is deleted and the next request will be rendered again and counted towards your quota.

Cache URL will not be accessible after the cache TTL is reached. It is recommended to avoid using it and always render screenshots and videos with the rendering API request. It will rely on the cache anyway (if specified).

## Support

In case if you have any issues with caching or any ideas on how to improve it and make it better, please contact us at [support@screenshotone.com](mailto:support@screenshotone.com).

# Host Returned Error

It is an API error returned when the host server does not respond with a successful status code within the range of 200-299.

```json
{
    "is_successful": false,
    "error_code": "host_returned_error",
    "error_message": "If the host doesn't respond successfully within the range of 200-299 status codes, the API won't take a screenshot. You can force the API to take a screenshot of the error page by specifying `ignore_host_errors`=true. You can get the returned status code from the site by reading the `returned_status_code` field.",
    "documentation_url": "https://screenshotone.com/docs/errors/host-returned-error/"
}
```

## Reasons and how to fix

### Host Returned Non-Success Status Code

The most common reason for the "host_returned_error" error is that the host server returned a status code outside the 200-299 range, indicating an unsuccessful response.

To fix this, you can:

1. **Check host server status**: Ensure the host server is operational and capable of returning a successful status code.
2. **Review site response**: Investigate the response from the host server to understand why it is not returning a successful status code.

### Forcing Screenshot of Error Pages

If you want the API to take a screenshot of the error page even when the host returns an error, you can use the `ignore_host_errors` option.

To fix this, set `ignore_host_errors` to `true` in your API request:

```json
{
    "ignore_host_errors": true
}
```

## Retrieving the Returned Status Code

You can get the status code returned by the host server by reading the `returned_status_code` field in the response. This will help in diagnosing and understanding the nature of the error.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Invalid Storage Configuration

It is an API error returned when the storage configuration for S3 is invalid.

```json
{
    "is_successful": false,
    "error_code": "invalid_storage_configuration",
    "error_message": "If you haven't created the bucket in the `us-east-1` AWS region, please, specify your bucket region through an endpoint in a format like https://s3.<your-region>.amazonaws.com.",
    "documentation_url": "https://screenshotone.com/docs/errors/invalid-storage-configuration/"
}
```

## Reasons and how to fix

### Incorrect AWS S3 Bucket Region

One common reason for the "invalid_storage_configuration" error is that the S3 bucket is not created in the `us-east-1` region and the bucket region is not specified correctly.

To fix this, you can:

1. **Specify the bucket Region**: Ensure you specify your bucket region in the endpoint format like `https://s3.<your-region>.amazonaws.com`. Replace `<your-region>` with the actual AWS region where your bucket is located.

### Missing or misconfigured Bucket

If the S3 bucket does not exist or is misconfigured, this can lead to the "invalid_storage_configuration" error.

To fix this, consider:

1. **Verify bucket existence**: Check that the S3 bucket exists in your AWS account and is accessible.
2. **Correct bucket configuration**: Ensure the bucket is configured correctly, including permissions and policies.

### Incorrect Endpoint URL

The endpoint URL might be incorrectly formatted, causing the API to fail in accessing the specified S3 bucket.

To fix this, ensure the endpoint URL is correctly formatted as `https://s3.<your-region>.amazonaws.com`, with the correct region specified.

### AWS IAM Permissions

Inadequate permissions set in the AWS IAM policies might prevent the API from accessing the S3 bucket, leading to this error.

To fix this, ensure that the IAM roles and policies associated with your bucket have the necessary permissions to allow access from the API.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Name Not Resolved

It is an API error returned when the domain name of the requested URL cannot be resolved.

```json
{
    "is_successful": false,
    "error_code": "name_not_resolved",
    "error_message": "Usually, the error happens when the domain name of the requested URL is not resolved. If you are trying to take a screenshot of a new site, please, wait a bit until the DNS records are refreshed.",
    "documentation_url": "https://screenshotone.com/docs/errors/name-not-resolved/"
}
```

## Reasons and how to fix

### Unresolved Domain Name

The most common reason for the "name_not_resolved" error is that the domain name of the requested URL cannot be resolved to an IP address. This often occurs with new domains or recently updated DNS records.

To fix this, you can:

1. **Wait for the DNS propagation if it is your website**: If you are trying to take a screenshot of a new site, wait for the DNS records to propagate fully. This can take anywhere from a few minutes to 48 hours.
2. **Or check DNS configuration**: Ensure that the DNS configuration for the domain is correct and that the records are properly set up.

### Temporary DNS Issues

Temporary DNS issues can also cause the "name_not_resolved" error. These can be due to network problems, DNS server issues, or other transient conditions.

To fix this, consider simply retrying the request after a short wait

### Incorrect Domain Name

If the domain name is incorrectly typed or does not exist, the API will not be able to resolve it.

To fix this, verify that the domain name in the request is correct and exists.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Network Error

It is an API error returned when the API cannot connect to the target host.

```json
{
    "is_successful": false,
    "error_code": "network_error",
    "error_message": "The error happens when the API can't connect to the provided URL. It might mean that the site blocks the API or is temporarily unavailable. Generally, you can safely retry to take a screenshot.",
    "documentation_url": "https://screenshotone.com/docs/errors/network-error/"
}
```

## Reasons and how to fix

### Proxy issues

If you use an external [proxy](/docs/guides/how-to-use-proxies/), make sure that it has access to the target host.

Also, often when you use proxy providers, you might not notice that you don't have sufficient credits to keep using proxy.

We noticed that for some providers, you sometimes need to recreate your proxy user/account to make it work again.

Also, many providers might block ScreenshotOne API IP addresses. In that case, consider adding [our IP ranges](/docs/ip-ranges/) to the proxy provider's allow list.

### The API is under heavy load

Rarely but under heavy load, ScreenshotOne API might fail to connect to target hosts. In that case, retry requests.

## Reach out to support

If nothing helps you, please, reach out to `support@screenshotone.com` and we will try to help you as fast as possible.

# Request Aborted

It is an API error returned when the request was aborted either by the user or the intermediate proxies and can't be fulfilled.

```json
{
    "is_successful": false,
    "error_code": "request_aborted",
    "error_message": "The request was aborted either by the user or the intermediate proxies and can't be fulfilled. If the error persists, please, reach out to `support@screenshotone.com`.",
    "documentation_url": "https://screenshotone.com/docs/request-aborted/"
}
```

## Reasons and how to fix

### HTTP Client Timeouts

One common reason for the "request_aborted" error is HTTP client timeouts. This occurs when the client (e.g., a web browser or a server making a request) has a timeout setting that is shorter than the time it takes for the request to be processed.

To fix this, you can increase the timeout setting in your HTTP client configuration.

### Local Development Live Reloading

During local development, live reloading tools (such as those used in web development environments) may cause requests to be aborted if the server restarts or if the code is recompiled. This can lead to the "request_aborted" error.

To avoid this, ensure that you have a stable development environment and minimize the frequency of live reloads while making API requests.

### Edge Function Timeouts

If you are using edge functions or serverless functions (e.g., AWS Lambda, Vercel Edge Functions), they might have their own timeout settings. When these timeouts are exceeded, the request will be aborted, resulting in the "request_aborted" error.

To fix this, you should increase the timeout settings for your edge functions.

## Reach out to support

If nothing helps you, please, reach out to `support@screenshotone.com` and we will try to help you as fast as possible.

# Request Body Too Large

It is an API error returned when the API fails to serve the request due to internal reasons:

```json
{
    "is_successful": false,
    "error_message": "The request body is too large. Please, reduce the size of the request body or reach out to `support@screenshotone.com` for assistance.",
    "error_code": "request_body_too_large",
    "documentation_url": "https://screenshotone.com/docs/errors/request-body-too-large/"
}
```

## How to fix

Reduce the size of the request body. It should be no more than 50MB.

## Reach out to support

If nothing helps you, please, reach out to `support@screenshotone.com` and we will try to help you as fast as possible.

# Resulting Image Too Large

It is an API error returned when the resulting image is too large for the specified format.

```json
{
    "is_successful": false,
    "error_message": "The resulting image is too large for the specified format.",
    "error_code": "resulting_image_too_large",
    "documentation_url": "https://screenshotone.com/docs/errors/resulting-image-too-large/"
}
```

## Reasons and how to fix

### Using image formats with size limits for full-page screenshots

The JPEG format has a height limit of 65,535 pixels, WebP format has a height limit of 16,383 pixels.

Full-page screenshots that don't fit the size limits will trigger the error `resulting_image_too_large`. 

A solution would be is to choose the format that fits your use case better. E.g. if you use WebP, try to use JPEG. Or maybe try PNG. 

### Limiting the height of the full-page screenshot

If it happens for full-page screenshots, you can set the `full_page_max_height` option to make sure the height of the resulting image always fits the specified format, e.g. set it to 16000 for WebP format or 60000 for JPEG format. 


### Reducing the device scale factor

If the issue is with the size of the page, you can try to reduce the device scale factor by setting the `device_scale_factor` option to a lower value, e.g. `1` instead of `2`.

## Combining the options

You can try to combine all the options above to find the best solution for your use case. 

Or you can even send API requests as-is, but when you encounter the error, just perform a retry with the limited full page height or lower device scale factor, or even a different format.

## Reach out to support

If you continue to face issues, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Request Invalid

It is an API error returned when the API fails to serve the request due to internal reasons:

```json
{
    "is_successful": false,
    "error_message": "The request parameters are not valid. You can look at the `error_details` response field to get more details.",
    "error_details": {
        // ... validation errors ...    
    },
    "error_code": "request_invalid",
    "documentation_url": "https://screenshotone.com/docs/errors/request-invalid/"
}
```

## Reasons and how to fix

### Invalid Request Parameters

The most common reason for the "request_not_valid" error is that one or more of the request parameters are invalid or missing.

To fix this, you can:

1. **Check `error_details` property**: Review the `error_details` field in the response to get specific information about which parameters are invalid.
2. **Correct request parameters**: Ensure that all required parameters are included in the request and that they are correctly formatted and valid.

### Missing Required Parameters

If required parameters are missing from the request, this will trigger the "request_not_valid" error.

To fix this, ensure that all mandatory parameters are provided in the request. Refer to the API documentation for a list of required parameters.

### Incorrect Data Types

Providing parameters with incorrect data types (e.g., a string instead of an integer) can lead to this error.

To fix this, verify that the data types of all parameters match the expected types as specified in the API documentation.

### Parameter Value Constraints

Some parameters may have constraints on their values (e.g., minimum or maximum length, specific formats). Violating these constraints will result in this error.

To fix this, check the constraints for each parameter in the API documentation and ensure that the provided values comply with these constraints.

### Syntax Errors

Syntax errors in the request, such as missing commas or brackets in JSON, can make the request invalid.

To fix this, carefully review the syntax of your request and correct any errors. Using a JSON validator can help identify syntax issues.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Script Trigger Redirect

It is an API error returned when the API detects that the script will trigger a redirect and screenshots won't be rendered successfully.

```json
{
    "is_successful": false,
    "error_code": "script_triggers_redirect",
    "error_message": "The specified \"scripts\" option might trigger a redirect, please, specify the \"scripts_wait_until\" option. If you think it is a mistake, please, reach out at `support@screenshotone.com`.",
    "documentation_url": "https://screenshotone.com/docs/script-triggers-redirect/"
}
```

## Reasons and how to fix

Let's quickly consider possible reasons and possible solutions.

### Add some wait options

Since the custom script you add with the "scripts" options triggers a redirect, you must also set [the "scripts_wait_until" option](/docs/options/#scripts_wait_until), too.

And to force the API to wait until the new page is loaded.

## Reach out to support

If nothing helps you, please, reach out to `support@screenshotone.com` and we will try to help you as fast as possible.

# Selector Not Found

It is an API error returned when the specified selector is not found or not visible within the given timeout period.

```json
{
    "is_successful": false,
    "error_code": "selector_not_found",
    "error_message": "If `selector` is specified and `error_on_selector_not_found`=true, or `click` is specified and `error_on_click_selector_not_found`=true, the error will be returned if the element by selector is not visible or it took more than timeout seconds to render it, but not more than 30 seconds.",
    "documentation_url": "https://screenshotone.com/docs/errors/selector-not-found/"
}
```

## Reasons and how to fix

### Selector Not Visible

The most common reason for the "selector_not_found" error is that the element specified by the selector is not visible on the page within the given timeout period.

To fix this, you can:

1. **Check the selector**: Ensure that the selector you are using is correct and matches an element on the page.
2. **Increase timeout**: If the element takes longer to load, increase the timeout value to give the element more time to become visible.

### Element is visible but has zero height

If there is an empty element on the page, the API will not be able to take a screenshot of it. In that case you will still get the "selector_not_found" error.

One of the ways to still get a screenshot is to make sure that [`error_on_selector_not_found`](https://screenshotone.com/docs/options/#error_on_selector_not_found) is set to `false` (and it is `false` by default).

You will get then the screenshot of the page instead of the error.

### Incorrect Selector

An incorrect or invalid selector can lead to this error, as the API cannot find the element on the page.

To fix this, verify that the selector is correctly specified and matches the element you want to target.

### Element Not Rendered

If the element is not rendered within the timeout period (not more than 30 seconds), the error will be triggered.

To fix this, ensure that the element is being rendered properly and within the expected time frame. You might need to investigate any delays in rendering the element.

### Conditional Visibility

If the element's visibility is conditional (e.g., depends on user interaction or specific page states), it might not be visible when the API checks for it.

To fix this, ensure that the conditions for the element's visibility are met before making the API request.

### Page Load Issues

Page load issues or JavaScript errors on the page can prevent the element from becoming visible.

To fix this, check for any page load issues or JavaScript errors that might be interfering with the rendering of the element.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Signature Invalid

It is an API error returned when the provided signature parameter is not valid.

```json
{
    "is_successful": false,
    "error_code": "signature_is_not_valid",
    "error_message": "You provided the `signature` parameter, but it is not valid. Make sure you use the correct signing algorithm—https://screenshotone.com/docs/signed-requests/.",
    "documentation_url": "https://screenshotone.com/docs/errors/signature-is-invalid/"
}
```

## Reasons and how to fix

### Incorrect Signing Algorithm

The most common reason for the "signature_is_not_valid" error is using an incorrect signing algorithm to generate the signature.

To fix this, you can:

1. **Verify signing algorithm**: Ensure you are using the correct signing algorithm as specified in the [signed requests documentation](https://screenshotone.com/docs/signed-requests/).
2. **Check signature generation code**: Review your code that generates the signature to ensure it follows the correct algorithm and procedure.

### Mismatched Signature

The signature provided in the request might not match the expected signature due to data mismatches or incorrect key usage.

To fix this, consider:

1. **Verify request data**: Ensure that all data used to generate the signature matches the data sent in the request.
2. **Use correct secret key**: Ensure that the correct secret key is used to generate the signature.

### Signature Formatting Issues

Formatting issues, such as encoding problems or extra characters, can lead to an invalid signature.

To fix this, verify that the signature is correctly formatted and encoded as required by the API.

### Debugging Signature Issues

If you are still encountering issues, you can use debugging tools or logging to trace the signature generation process and identify where it might be going wrong.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Signature Required

It is an API error returned when the signature parameter is missing in the request.

```json
{
    "is_successful": false,
    "error_code": "signature_is_required",
    "error_message": "The `signature` parameter is required. Because signing requests is required in the access page—https://dash.screenshotone.com/access. Make sure you use the correct signing algorithm—https://screenshotone.com/docs/signed-requests/.",
    "documentation_url": "https://screenshotone.com/docs/errors/signature-is-required/"
}
```

## Reasons and how to fix

### Missing Signature Parameter

The most common reason for the "signature_is_required" error is that the `signature` parameter is not included in the request. This parameter is mandatory for authenticating and authorizing the API request if on the [access dashboard page](https://dash.screenshotone.com/access) forcing signing requests is activated.

To fix this, ensure that you include the `signature` parameter in your API request.

### Programmatic Issues

If you are dynamically generating requests (e.g., through a script or application), there might be a bug causing the `signature` to be omitted.

To fix this, debug your script or application to ensure the `signature` is being properly set and included in every API request.

### Request Validation

To ensure your request is valid, double-check all parameters and the generated signature before sending the request to the API.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Storage Returned Transient Error

It is an API error returned when the storage server returns a transient error and retries have been exhausted.

```json
{
    "is_successful": false,
    "error_code": "storage_returned_transient_error",
    "error_message": "The storage returned an HTTP status code between 500 and 599 and we exhausted retries. You can likely retry the request again.",
    "documentation_url": "https://screenshotone.com/docs/errors/storage-returned-transient-error/"
}
```

## Reasons and how to fix

### Transient Storage Server Error

The most common reason for the "storage_returned_transient_error" is that the S3 storage returned an HTTP status code between 500 and 599, indicating a transient error.

To fix this, you can:

1. **Retry the request**: Since the error is transient, retrying the request after a short wait is often effective.
2. **Check storage service status**: Verify the status of the storage service you are using to see if there are any ongoing issues or maintenance that might be causing the error.

### Exhausted Retries

The API has attempted to retry the request multiple times but has exhausted its retry limit.

To fix this, consider implementing additional retries on your end, with exponential backoff to avoid overwhelming the storage server.

### Temporary Network Issues

Temporary network issues can also cause transient errors from the storage server.

To fix this, ensure that your network connection is stable and retry the request.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Temporary Unavailable

It is an API error returned when the API is temporarily unavailable due to an error or overload.

```json
{
    "is_successful": false,
    "error_code": "temporary_unavailable",
    "error_message": "The API is temporarily unavailable due to an error or overload. Please wait a bit and then safely retry your request.",
    "documentation_url": "https://screenshotone.com/docs/errors/temporary-unavailable/"
}
```

## Reasons and how to fix

### API Overload

One common reason for the "temporary_unavailable" error is that the API is overloaded with requests, causing temporary unavailability.

To fix this, you can:

1. **Wait and retry**: Wait for a short period and then retry your request. The API should become available once the load decreases.
2. **Rate limiting**: Implement rate limiting on your end to avoid overwhelming the API with too many requests in a short period.

### Temporary Errors

Temporary errors or issues within the API infrastructure can also cause this error.

To fix this, consider:

1. **Retry the request**: Since the issue is temporary, retrying the request after a brief wait is often effective.
2. **Monitor status page**: Check [the API status page](https://status.screenshotone.com/) to see if there are any ongoing issues.

### Scheduled Maintenance

The API might be undergoing scheduled maintenance, leading to temporary unavailability.

### Network Issues

Network issues between your system and the API server can also result in this error.

To fix this, ensure your network connection is stable and retry the request.

## Implementing Retry Logic

Implementing retry logic in your application can help handle temporary unavailability gracefully. Use exponential backoff strategy for retries to avoid overwhelming the API further.

## Reach out to support

If you continue to face issues or need further assistance, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Timeout Error

It is an API error returned when the API can't render screenshots or video within the specified timeout:

```json
{
  "is_successful": false,
  "error_code": "timeout_error",
  "error_message": "The screenshot couldn't be taken within the specified timeout. Either the site doesn't respond quickly, or rendering takes longer than expected. Play with the `timeout` or the `navigation_timeout` options or reach the support for the investigation.",
  "documentation_url": "https://screenshotone.com/docs/errors/"
}
```

## Reasons and how to fix

Let's quickly consider possible reasons and possible solutions.

### Timeout is too small

By default, the timeout is about 60 seconds. You must fit your rendering request within that timeout.

You can:

Either use asynchronous requests and webhooks to get the results. And set the timeout up to 300 seconds.
Or you can try to increase the timeout up to 90 seconds.

### Delay is too big

Make sure that your delay is not too big, e.g. if you set it to 30 seconds, and it takes the website to load for 30 seconds, it is better to decrease the delay.

### A website is not loading properly

Some sites just take too much time to load or they don't emit DOMContentLoaded events.

Try to play with different values of [the wait_until option]() and see if it helps.

### Long duration of the video

Often when you record a video of a long duration, the API must not respond in time. Since it takes to both record a video and stream it.

Try to decrease the video duration you are recording, it might help.

## Reach out to support

If nothing helps you, please, reach out to `support@screenshotone.com` and we will try to help you as fast as possible.

# Invalid Header Parameter

It is an API error returned when the `headers` parameter is invalid.

```json
{
    "is_successful": false,
    "error_message": "The `headers` parameters you provided are invalid. Please, consider providing different values and adhere to the format specified in the ScreenshotOne documentation.",
    "error_code": "invalid_header_parameter",
    "documentation_url": "https://screenshotone.com/docs/errors/invalid-header-parameter/"
}
```

## Reasons and how to fix

### The format of the parameter is invalid

Make sure you adhere to the format specified in the [ScreenshotOne options documentation](https://screenshotone.com/docs/options/#headers). If you sent a GET request, your headers must be in the query string as:

```
headers=name1:val1&headers=name2:val2
```

If you sent a POST request, your headers must be in the request body as:

```json
{
    // ...
    "headers": ["name1:val1", "name2:val2"]
    // ...
}
```

## Reach out to support

If you continue to face issues, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Matched Failed Request

This API error is returned when a request matched by the specified pattern in the `fail_if_request_failed` option has been failed:

```json
{
    "is_successful": false,
    "error_code": "matched_failed_request",
    "error_message": "A request matched by the specified pattern by the `fail_if_request_failed` option has been failed. If it seems to be a mistake or not what you expected, please, reach out to `support@screenshotone.com` as quickly as possible, and we will assist and try to resolve your problem.",
    "documentation_url": "https://screenshotone.com/docs/errors/matched-failed-request/"
}
```

## Reasons and how to fix

The reason you get this error message is because you specified the [fail_if_request_failed](/docs/options/#fail_if_request_failed) option.

If you want to disable this behavior, you simply need to remove the parameter from your request. If you have a request like:

```
https://api.screenshotone.com/take?access_key=<your access key>&url=https://example.com&fail_if_request_failed=**example.com**
```

Make it like this:

```
https://api.screenshotone.com/take?access_key=<your access key>&url=https://example.com
```

In case, if the error persists, please immediately reach out to `support@screenshotone.com`, and we will try to fix that as soon as possible.

## Reach out to support

Also, if you encounter any issues or bugs, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# Invalid Cookie Parameter

It is an API error returned when the `cookies` parameter is invalid.

```json
{
    "is_successful": false,
    "error_message": "The `cookies` parameters you provided are invalid. Please, consider providing different values and adhere to the format specified in the ScreenshotOne documentation.",
    "error_code": "invalid_cookie_parameter",
    "documentation_url": "https://screenshotone.com/docs/errors/invalid-cookie-parameter/"
}
```

## Reasons and how to fix

### The format of the parameter is invalid

Make sure you adhere to the format specified in the [ScreenshotOne options documentation](https://screenshotone.com/docs/options/#cookies):

```
cookies=name1=val1; Domain=example.com; Secure; HttpOnly
```

It is not for demonstration purposes, but the string must be URL-encoded. 

If you need to specify multiple cookies, you can do it like this:

```
cookies=name1=val1; Domain=example.com; Secure; HttpOnly&cookies=name2=val2; Domain=example.com; Secure; HttpOnly
```

## Reach out to support

If you continue to face issues, please reach out to `support@screenshotone.com`, and we will assist you as soon as possible.

# C# (.NET) SDK and Code Examples

import Alert from "@/components/Alert.astro";

<Alert>
    If you have any questions, please, reach out at `support@screenshotone.com`.
</Alert>

<Alert>
    Massive thanks and rays of goodness to Andy Robinson ([Indie
    Hackers](https://www.indiehackers.com/TheOrigin),
    [GitHub](https://github.com/theorigin)) for providing the fully-featured
    high-quality C# (.NET) SDK.
</Alert>

### Installation

Add the library via nuget using the package manager console:

```bash
PM> Install-Package ScreenshotOne.dotnetsdk
```

Or from the .NET CLI as:

```bash
dotnet add package ScreenshotOne.dotnetsdk
```

### Usage

Don't forget to [sign up](https://dash.screenshotone.com/sign-up) to get access and secret keys.

Generate a screenshot URL without executing request:

```csharp
var client = new Client("&lt;access key&gt;", "&lt;secret key&gt;");
var options = TakeOptions.Url("https://www.amazon.com")
  .FullPage(true)
  .Format(Format.PNG)
  .BlockCookieBanners(true);

var url = client.GenerateTakeUrl(options);

// url = https://api.screenshotone.com/take?url=https%3A%2F%2Fwww.amazon.com&full_page=true&format=png&block_cookie_banners=true&access_key=_OzqMIjpCw-ARQ&signature=8a08e62d13a5c3490fda0734b6707791d3decc9ab9ba41e8cc045288a39db502

```

Take a screenshot and save the image in the file:

```csharp
var client = new Client("&lt;access key&gt;", "&lt;secret key&gt;");
var options = TakeOptions.Url("https://www.google.com")
  .FullPage(true)
  .Format(Format.PNG)
  .BlockCookieBanners(true);

var bytes = await client.Take(options);

File.WriteAllBytes(@"c:\temp\example.png", bytes);
```

Check out [other SDKs and code examples](/docs/code-examples/).

# Go SDK and Code Examples

import Alert from "@/components/Alert.astro";

<Alert>
    If you have any questions, please, reach out at `support@screenshotone.com`.
</Alert>

It takes minutes to start taking screenshots in Go. Just [sign up](https://dash.screenshotone.com/sign-up) to get access and secret keys, import the client, and you are ready to go.

### Installation

```shell
go get github.com/screenshotone/gosdk
```

### Usage

Import the library:

```go
import screenshots "github.com/screenshotone/gosdk"
```

Generate a screenshot URL without executing request:

```go
client, err := screenshots.NewClient("IVmt2ghj9TG_jQ", "Sxt94yAj9aQSgg")
if err != nil {
    // ...
}

options := screenshots.NewTakeOptions("https://scalabledeveloper.com").
    Format("png").
    FullPage(true).
    DeviceScaleFactor(2).
    BlockAds(true).
    BlockTrackers(true)

u, err := client.GenerateTakeURL(options)
if err != nil {
    // ...
}

fmt.Println(u.String())
// Output: https://api.screenshotone.com/take?access_key=IVmt2ghj9TG_jQ&block_ads=true&block_trackers=true&device_scale_factor=2&format=png&full_page=true&url=https%3A%2F%2Fscalabledeveloper.com&signature=85aabf7ac251563ec6158ef6839dd019bb79ce222cc85288a2e8cea0291a824e
```

Take a screenshot and save the image in the file:

```go
client, err := screenshots.NewClient("IVmt2ghj9TG_jQ", "Sxt94yAj9aQSgg")
if err != nil {
    // ...
}

options := screenshots.NewTakeOptions("https://example.com").
    Format("png").
    FullPage(true).
    DeviceScaleFactor(2).
    BlockAds(true).
    BlockTrackers(true)

image, err := client.Take(context.TODO(), options)
if err != nil {
    // ...
}

defer image.Close()
out, err := os.Create("example.png")
if err != nil {
    // ...
}

defer out.Close()
io.Copy(out, image)
```

Check out [other SDKs and code examples](/docs/code-examples/).

# Java SDK and Code Examples

import Alert from "@/components/Alert.astro";

<Alert>
    If you have any questions, please, reach out at `support@screenshotone.com`.
</Alert>

It takes minutes to start taking screenshots in Java. Just [sign up](https://dash.screenshotone.com/sign-up) to get access and secret keys, import the client, and you are ready to go.

### Installation

Add dependency to your `pom.xml`:

```xml
<dependencies>
    <dependency>
        <groupId>com.screenshotone.jsdk</groupId>
        <artifactId>screenshotone-api-jsdk</artifactId>
        <version>[1.0.0,2.0.0)</version>
    </dependency>
</dependencies>
```

### Usage

Generate a screenshot URL without executing request:

```java
import com.screenshotone.jsdk.Client;
import com.screenshotone.jsdk.TakeOptions;

public class App {
    public static void main(String[] args) throws Exception {
        final Client client = Client.withKeys("IVmt2ghj9TG_jQ", "Sxt94yAj9aQSgg");
        TakeOptions takeOptions = TakeOptions.url("https://scalabledeveloper.com")
                .fullPage(true)
                .deviceScaleFactor(1)
                .viewportHeight(1200)
                .viewportWidth(1200)
                .format("png")
                .omitBackground(true);
        final String url = client.generateTakeUrl(takeOptions);

        System.out.println(url);
        // Output: https://api.screenshotone.com/take?access_key=IVmt2ghj9TG_jQ&device_scale_factor=1&format=png&full_page=true&omit_background=true&url=https%3A%2F%2Fscalabledeveloper.com&viewport_height=1200&viewport_width=1200&signature=3c0c5543599067322e8c84470702330e3687c6a08eef6b7311b71c32d04e1bd5
    }
}
```

Usually you generate URL to place it inside the image tag (<img />) or to share it.

Take a screenshot and save the image in the file:

```java
import com.screenshotone.jsdk.Client;
import com.screenshotone.jsdk.TakeOptions;

import java.io.File;
import java.nio.file.Files;

public class App {
    public static void main(String[] args) throws Exception {
        final Client client = Client.withKeys("IVmt2ghj9TG_jQ", "Sxt94yAj9aQSgg");
        TakeOptions takeOptions = TakeOptions.url("https://scalabledeveloper.com")
                .fullPage(true)
                .deviceScaleFactor(1)
                .viewportHeight(1200)
                .viewportWidth(1200)
                .format("png")
                .omitBackground(true);
        final byte[] image = client.take(takeOptions);

        Files.write(new File("./example.png").toPath(), image);
    }
}
```

Check out [other SDKs and code examples](/docs/code-examples/).

# SDK and Code Examples

import Alert from "@/components/Alert.astro";

<Alert>
    If you have any questions, please, reach out at `support@screenshotone.com`.
</Alert>

There is a set of native SDKs you can use: 

* [Go](/docs/code-examples/go/)
* [Java](/docs/code-examples/java/)
* [PHP](/docs/code-examples/php/)
* [Ruby](/docs/code-examples/ruby/)
* [Python](/docs/code-examples/python/)
* [C# (.NET)](/docs/code-examples/c-net/)
* [JavaScript and TypeScript (Node.js)](/docs/code-examples/c-net/)

If your language is not supported, please, reach out to support@screenshotone.com and we will try to close it quickly. Otherwise, you can always use any HTTP client.

# PHP SDK and Code Examples

import Alert from "@/components/Alert.astro";

<Alert>
    If you have any questions, please, reach out at `support@screenshotone.com`.
</Alert>

### Installation

Run the next command to install the PHP SDK to take screenshots:

```shell
composer require screenshotone/sdk:^1.0
```

### Usage

Don't forget to [sign up](https://dash.screenshotone.com/sign-up) to get access and secret keys.

Generate a screenshot URL without executing the request. Or download the screenshot. It is up to you:

```php
<?php

use ScreenshotOne\Sdk\Client;
use ScreenshotOne\Sdk\TakeOptions;

$client = new Client('<access key>', '<secret key>');

$options = TakeOptions::url("https://example.com")
    ->fullPage(true)
    ->delay(2)
    ->geolocationLatitude(48.857648)
    ->geolocationLongitude(2.294677)
    ->geolocationAccuracy(50);

$url = $client->generateTakeUrl($options);
echo $url.PHP_EOL;
// expected output: https://api.screenshotone.com/take?url=https%3A%2F%2Fexample.com...

$image = $client->take($options);
file_put_contents('example.png', $image);
// the screenshot is stored in the example.png file
```

Check out [other SDKs and code examples](/docs/code-examples/).

# Python SDK and Code Examples

import Alert from "@/components/Alert.astro";

<Alert>
    If you have any questions, please, reach out at `support@screenshotone.com`.
</Alert>

### Installation

Run the next command to install the Python SDK to take screenshots:

```shell
pip install screenshotone
```

### Usage

Don't forget to [sign up](https://dash.screenshotone.com/sign-up) to get access and secret keys.

Generate a screenshot URL without executing the request. Or download the screenshot. It is up to you:

```python
import shutil
from screenshotone import Client, TakeOptions

# create API client
client = Client('<your access key>', '<your secret key>')

# set up options
options = (TakeOptions.url('https://screenshotone.com')
    .format("png")
    .viewport_width(1024)
    .viewport_height(768)
    .block_cookie_banners(True)
    .block_chats(True))

# generate the screenshot URL and share it with a user
url = client.generate_take_url(options)
# expected output: https://api.screenshotone.com/take?url=https%3A%2F%2Fscreenshotone.com&viewport_width=1024&viewport_height=768&block_cookie_banners=True&block_chats=True&access_key=<your access key>&signature=6afc9417a523788580fa01a9f668ea82c78a9d2b41441d2a696010bf2743170f

# or render a screenshot and download the image as stream
image = client.take(options)

# store the screenshot the example.png file
with open('example.png', 'wb') as result_file:
    shutil.copyfileobj(image, result_file)
```

Check out [other SDKs and code examples](/docs/code-examples/).

# Ruby SDK and Code Examples

import Alert from "@/components/Alert.astro";

<Alert>
    If you have any questions, please, reach out at `support@screenshotone.com`.
</Alert>

<Alert>
    Massive thanks and rays of goodness to [Gustavo
    Garcia](https://twitter.com/theluctus) from
    [Dailytics](https://dailytics.com/) for providing the fully-featured
    high-quality Ruby SDK.
</Alert>

### Installation

Update your Gemfile:

```
gem 'screenshotone'
```

Then execute:

```shell
bundle install
```

### Usage

Don't forget to [sign up](https://dash.screenshotone.com/sign-up) to get access and secret keys.

Generate a screenshot URL without executing the request. Or download the screenshot. It is up to you:

```ruby
# If you don't need to add a signature
client = ScreenshotOne::Client.new('my_access_key')

# If you do need to add a signature
client = ScreenshotOne::Client.new('my_access_key', 'my_secret_key')

# You can set any available option, in a camel_case format, for example:
options = ScreenshotOne::TakeOptions.new(url: 'https://example.com').
            full_page(true).
            delay(2).
            geolocation_latitude(48.857648).
            geolocation_longitude(2.294677).
            geolocation_accuracy(50)

# Verify all the parameters are valid (we will validate the parameters that should be
# numeric, booleans or that accept only certain values)
options.valid?
=> true

# To simply get the final url:
client.generate_take_url(options)
=> "https://api.screenshotone.com/take?url=https%3A%2F%2Fexample.com..."

# To actually get the image (the response body of a request to the previous url)
client.take(options)
=> "\xFF\xD8\xFF\xE0\x00\x10JFIF\x00\x01\x01\x00\x00\x01\x00\x01\x00\x00\xFF\..."
```


Check out [other SDKs and code examples](/docs/code-examples/).

# Charging Extra

You can set the hard limit for screenshots higher than the limit in your current plan. And by doing this, you are enabling charging for extra screenshots. The option is available only for paying customers who are organization owners.

![Changing the hard limit](charge-extra.png)

Once the charging extra is enabled (at [your subscription page](https://dash.screenshotone.com/subscription)), you will be charged for successful not cached requests that go over your plan limitation.

## Examples

:::note
**Your price per extra screenshot depends on the plan you have**. You can see all prices at the [ScreenshotOne Pricing page](https://screenshotone.com/pricing) or check out your price at [your subscription page](https://dash.screenshotone.com/billing).
:::

Let's look at different examples of an artificial subscription plan. Imagine you have a limit of 10000 screenshots monthly, and let's assume the price of one extra screenshot is $0.004 (this is an example price, not a real price):

1. The plan limit is 10000, the hard limit is 15000, and you rendered 12000 screenshots. You will be charged for 2000 extra screenshots. $0.004 x 2000 = $8.
2. The plan limit is 10000, the hard limit is 15000, and you rendered 12500 screenshots. You will be charged for 3000 extra screenshots. $0.004 x 3000 = $12.

Why for 3000 extra screenshots?

**It is because extra charges are rounded to the close upper bound of a thousand screenshots.**

If you render only one extra screenshot, you pay for 1000 screenshots. If you render 1001, you pay for 2000, and so on. If you render 999, you pay for 1000, and so on.

## Upgrading subscription

Once you upgrade your subscription, your hard limit is reset. And you need to set it up again.

## Cancelling or downgrading subscription

Before you cancel your subscription, ScreenshotOne will try to charge you for extra screenshots and only then cancel it.

For downgrading, charging happens only when downgrading to a free plan. Otherwise, there is no need.

## When you are charged

ScreenshotOne charges you periodically over the extra usage if needed, usually once per 1000 screenshots.

Or you also might be charged in one "batch" for the extra usage. It depends on the internal logic of the service.

## Maximum hard limit

Every new customer has a maximum hard limit of 100,000 screenshots. If you need to upgrade it and make it higher, feel free to write to `support@screenshotone.com`. Please, describe your use case.

ScreenshotOne is a scalable and highly performant API that has paying customers who make render more than 100,000 screenshots monthly. Still, there is a need to make sure that there is no service abuse and that high-quality service can be delivered. That's why the maximum hard limit for new customers is applied.

# How to render website screenshots with Bubble

Bubble is a full-stack no-code app builder. It is a platform, where you can design, build, and launch fully functional web and mobile applications. They also handle all the technical details, like servers, integrations, and security.

In case if you are going to build a website directory or your application needs website screenshots, you can use ScreenshotOne to do that for you. 

## Community Plugins and Integrations

To integrate ScreenshotOne with Bubble for rendering website screenshots, you can use [a ScreenshotOne plugin for Bubble provided Revido](https://bubble.io/plugin/screenshotone-1732272787355x675035896606359600).

The plugin is developed and supported by [Revido—a company that build products for their customers through low-code](https://revido.co).

# How to automate website screenshots with Zapier

Zapier is a powerful automation platform that lets you connect your apps and automate workflows without writing any code. These automated workflows, called "Zaps", can connect thousands of apps to help you save time and reduce manual work.

With ScreenshotOne's Zapier integration, you can easily incorporate website screenshot generation into your automated workflows, making it simple to capture and process screenshots as part of your business processes.

You can use Zapier to automatically trigger screenshot captures and send them to your favorite apps like Google Drive, Slack, or any of the thousands of apps Zapier supports.

## Integrations 

Check out [ScreenshotOne integrations on Zapier](https://zapier.com/apps/screenshotone/integrations) and [a help guide provided by Zapier](https://help.zapier.com/hc/en-us/articles/16307799273613-How-to-get-started-with-ScreenshotOne-on-Zapier).

## Tutorials 

### Screenshots to Google Drive with Zapier

A guide by [Toolfolio](https://toolfolio.io/) on [how to automate website screenshots upload to Google Drive with Zapier](https://toolfolio.io/productive-value/automate-website-screenshots-with-zapier-screenshotone).

### Troubleshooting

#### Timeouts

Zapier has [a timeout limit of 30 seconds for executing a Zap](https://docs.zapier.com/platform/build/troubleshoot-action-timeouts). If you encounter timeouts, you can try the following:

1. If it is [a full-page screenshot, try to optimize it](/docs/guides/performance/). E.g. disable full page scrolling.
2. Or use [webhooks instead and asynchronous requests](/docs/async-and-webhooks/).

## Support 

If you have any questions, don't hesitate to reach out to our support at [support@screenshotone.com](mailto:support@screenshotone.com).

# Screenshot Options

import Alert from "@/components/Alert.astro";
import Details from "@/components/docs/Details.astro";

This document lists all available request options to take screenshots of websites, render HTML, or Markdown.

## Credentials

### access_key

Each request must have an access key to authenticate the API user. You can find it on the [access page](https://dash.screenshotone.com/access).

An example of the request URL with `access_key`:

```
https://api.screenshotone.com/take?url=https://apple.com&access_key=<your access key>
```

<Details>
    ![A screenshot of the Apple site taken by screenshot
    API](./default_example.png)
</Details>

### signature

A signature is optional. It is used for [the signed requests](/docs/signed-requests).

<Alert>
    Do not use the secret (signing) key as a signature. A signature is a complex
    parameter that is [a hash of all screenshot parameters with a signing
    key](/docs/signed-requests).
</Alert>

You can force signing all requests [access page](https://dash.screenshotone.com/access).

## Essentials

### url

URL of the site to take a screenshot of. One of the [Markdown](#markdown), [HTML](#html) or [URL](#url) parameters is required.

An example of the request URL with `url=https://www.youtube.com/feed/explore`:

```
https://api.screenshotone.com/take?url=https://www.youtube.com/feed/explore&access_key=<your access key>
```

<Details>
    ![A screenshot of the Youtube site taken by screenshot
    API](./youtube_example.png)
</Details>

### html

HTML you want to render. One of the [Markdown](#markdown), [HTML](#html) or [URL](#url) parameters is required.

An example of the request URL with `html=<h1>Hello, world!</h1>`:

```
https://api.screenshotone.com/take?html=<h1>Hello,%20world!</h1>&access_key=<your access key>
```

<Details>
    ![A screenshot of the custom HTML taken by screenshot
    API](./html_example.png)
</Details>

### markdown

Markdown you want to render. One of the [Markdown](#markdown), [HTML](#html) or [URL](#url) parameters is required.

An example of the request URL with `markdown=# Hello, world!` (encoded to `markdown=%23%20Hello%2C%20world!`):

```
https://api.screenshotone.com/take?html=%23%20Hello%2C%20world!&access_key=<your access key>
```

<Details>
    ![A screenshot of the custom Markdown taken by screenshot
    API](./markdown.jpeg)
</Details>

### format

<Alert>
    You can get the HTML content of the page and image in one request by using
    the [metadata_content](#metadata_content) parameter.
</Alert>

Available response formats:

-   `png`
-   `jpeg` or `jpg`
-   `webp`
-   `gif`
-   `jp2`
-   `tiff`
-   `avif`
-   `heif`
-   `pdf` (see [PDF options](#pdf-rendering))
-   `html` (text representation)
-   `markdown` (text representation)

Default value is `jpg`.

An example of the request URL with `format=jpeg` (an alias for `format=jpg`):

```
https://api.screenshotone.com/take?format=jpeg&url=https://apple.com&access_key=<your access key>
```

<Details>
    ![A screenshot of the Apple site taken by screenshot
    API](./format_jpeg_example.jpeg)
</Details>

For the HTML format (`format=html`), consider including the shadow DOM elements with the [`include_shadow_dom`](#include_shadow_dom) option.

### response_type

Available response types:

-   `by_format` — return exactly the response defined in the [format option](#format). If `format=png`, the response will be the binary representation of the `png` with the content type header `image/png`;
-   `empty` — return only status or error. It is suitable when you want to [upload the screenshot to storage](#storing) and don't care about the results. It also speeds up the response since there are no networking costs involved.
-   `json` — A method returns the response in the JSON format, but it is only suitable if you use options that are effective for JSON. By default, the JSON response will be empty. But for example, when you use [caching](#caching), the JSON will be populated with additional data.

ScreenshotOne API doesn't support the `base64` encoding format. But you can get the screenshot in the binary format and convert it to the `base64` encoding with your language of choice.

The default value is `by_format`.

An example of the request URL:

```
https://api.screenshotone.com/take?response_type=empty&url=https://example.com&access_key=<your access key>
```

### selector

A CSS-like selector of the element to take a screenshot of. It is optional.

If the selector is specified and `error_on_selector_not_found=true`, the error will be returned if the element by selector is not visible or it took more than `timeout` seconds to render it, but not more than 30 seconds.

For HTML or Markdown formats, the selector returns the outer rendered HTML of the provided input.

Supports `shadow/` selectors which will traverse the shadow DOM elements. It will be slower, and if many elements have the same selectors, the first one will be chosen.

An example of the request URL with `selector=.content`:

```
https://api.screenshotone.com/take?selector=.content&url=https://scalabledeveloper.com/posts/context-in-go/&access_key=<your access key>
```

<Details>
    ![A screenshot of the content part of the Scalable Developer site taken by
    screenshot API](./scalable_developer_content_example.png)
</Details>

<br />

The same page without selector:

```
https://api.screenshotone.com/take?url=https://scalabledeveloper.com/posts/context-in-go/&access_key=<your access key>
```

<Details>
    ![A screenshot of the Scalable Developer site taken by screenshot
    API](./scalable_developer_example_without_selector.png)
</Details>

Setting the [selector](#selector) option changes the behavior of the [capture_beyond_viewport](#capture_beyond_viewport) option, and sets it to `true` by default.

### selector_algorithm

The default algorithm is `default` which means to use the browser tools to screenshot the element by selector. But the new algorithm `clip` allows more flexibility and better results for some cases.

E.g. if you need to screenshot the element by selector and the element is not fully visible, or it requires scrolling to screenshot the element, the `clip` algorithm will be more suitable.

An example of the API request URL with `selector_algorithm=clip`:

```
https://api.screenshotone.com/take?selector_algorithm=clip&selector=h1&url=https://example.com&access_key=<your access key>
```

### selector_scroll_into_view

When you take a screenshot of an element by [selector](#selector), there is a rare case where the page or the part of the element might not be visible on the viewport or 
the element might contain lazy loaded images or elements that are not visible on the viewport.

With the `selector_scroll_into_view` option, you control if you want to scroll the page to the element or not and to trigger lazy loaded images and elements.

The option is set to `true` by default.

### capture_beyond_viewport

When you take [a full page screenshot](#full_page) or a screenshot of an element by [selector](#selector), there is a rare case where the page or the part of the element might not be visible on the viewport.

With the `capture_beyond_viewport` option, you control if you want to take the screenshot of the full page or the element (`capture_beyond_viewport=true`) or if you are OK with taking a screenshot of the part of the page or the element (`capture_beyond_viewport=false`).

When you take [full page screenshot](#full_page) or you take screenshot of an element by [selector](#selector).

The option is set to `true` by default for the full-page screenshots, when [full_page](#full_page) is `true`.

You might find it useful to check out [the examples of how the captureBeyondViewport option works](/blog/capture-beyond-viewport-in-puppeteer-and-chrome-devtools-protocol) "examples of how the captureBeyondViewport option works").

The option is `true` by default for the screenshots by the [selector](#selector), too.

### scroll_into_view

It scrolls the page if needed and ensures that the given selector is present in the view when taking a screenshot.

If more than one element matches the selector, the first visible element in DOM is selected.

The element will be positioned at the top of the viewport. To adjust the position a bit before taking a screenshot, 
use the [scroll_into_view_adjust_top](#scroll_into_view_adjust_top) option.

In case, if the selector is not found, it will render the viewport at the top of the page. To change this behavior, use the [error_on_selector_not_found](#error_on_selector_not_found) option, set it to `true` to return an error if the selector is not found.

An example of the request URL:

```
https://api.screenshotone.com/take?scroll_into_view=%23faq&url=https://screenshotone.com&access_key=<your access key>
```

### scroll_into_view_adjust_top

After the given element appears in the viewport and its top coordinate is aligned with the viewport's top, you can adjust the position a bit before taking a screenshot by specifying the `scroll_into_view_adjust_top` parameter.

By default, it is `0`. But you can use negative and positive integers.

An example of the request URL:

```
https://api.screenshotone.com/take?scroll_into_view_adjust_top=-100&scroll_into_view=%23faq&url=https://screenshotone.com&access_key=<your access key>
```

### request_gpu_rendering

By default is disabled and currently available only for the top-tier paid plans.

Setting `request_gpu_rendering` to `true` hints API to route requests to servers with supported hardware rendering acceleration.

It is not 100% guaranteed to satisfied and software acceleration might be used as a fallaback, but most of the time the ScreenshotOne API will do its best to render screenshots with GPU support if the option is set to `true`.

However, you can use the `fail_if_gpu_rendering_fails` option to force the request to fail if GPU rendering fails.

### include_shadow_dom

By default is disabled and equals to `false`.

Setting `include_shadow_dom` to `true` will use a different method of content extraction for requests that has `format=html`
or request `metadata_content=true`. The API will try to include all open and closed shadow DOM roots in the content. By default, they are not included.

### attachment_name

The option allows you to specify the name of the attachment. The format will be added as a suffix to the name.

```
https://api.screenshotone.com/take?attachment_name=screenshot&url=https://example.com&access_key=<your access key>&format=jpg
```

It will trigger the browser to download the screenshot with the name `screenshot.jpg`

### external_identifier

You can set `external_identifier` parameter to any alphanumeric value. It will be included in the webhook request headers:

- `x-screenshotone-external-identifier`—external identifier. It is helpful for error and successful request tracking.

## PDF Rendering

If you want resulting PDF reflects a full page screenshot as close as possible, use the combination of next options:

```
format=pdf&media_type=screen&pdf_print_background=true&pdf_fit_one_page=true
```

### pdf_print_background

Set to `true` to print background graphics. The default value is `false`.

### pdf_fit_one_page

The default value is `false`.

When the option is set to `true``, the API will try to fit the website on one page. It is the closest equivalent to a full-page screenshot as a PDF without splitting into pages.

### pdf_landscape

Set to `true` to set PDF orientation to landscape. It is `false` by default. 

### pdf_paper_format

Specifies the paper format for the PDF output. Available options are:

- "a0": ISO A0 paper size (841 x 1189 mm)
- "a1": ISO A1 paper size (594 x 841 mm)
- "a2": ISO A2 paper size (420 x 594 mm)
- "a3": ISO A3 paper size (297 x 420 mm)
- "a4": ISO A4 paper size (210 x 297 mm)
- "a5": ISO A5 paper size (148 x 210 mm)
- "a6": ISO A6 paper size (105 x 148 mm)
- "legal": Legal paper size (8.5 x 14 inches)
- **"letter": Letter paper size (8.5 x 11 inches)—default.**
- "tabloid": Tabloid paper size (11 x 17 inches)

If not specified, the default paper format is "a4".

### pdf_margin

Specifies the margin for the PDF file. By default, the margin is `0`.

But you can set it to any value in string format, e.g. `pdf_margin=20px` or other supported units.

You can then override the margin for each side separately:

```
pdf_margin=20px&pdf_margin_top=0px
```

This will set the margin for all sides to `20px` except the top, which will be `0px`.

### pdf_margin_top

The top margin for the resulting PDF.

### pdf_margin_right

The top margin for the resulting PDF.

### pdf_margin_bottom

The top margin for the resulting PDF.

### pdf_margin_left

The top margin for the resulting PDF.

## OpenAI Vision Integration

ScreenshotOne supports direct integration with [OpenAI vision](https://platform.openai.com/docs/guides/vision), so you can get a screenshot and generate vision prompt completion in one simple API call with no additional cost.

You will get the result either as a `X-ScreenshotOne-Vision-Completion` header in the reponse or as:

```json
{

    "vision": {
        "completion": "..."
    }
}
```

If you use `response_type=json`.

### openai_api_key

Use your OpenAI API key to send requests to the OpenAI API key. It is not stored in the ScreenshotOne database.

### vision_prompt

Specify the prompt you want to use along with the screenshot of the site.

### vision_max_tokens

Specify how many tokens at max the GPT vision must return as a response.

## Clip

There is a guide on [how to screenshot an area of a site](/docs/guides/how-to-screenshot-an-area-of-a-site/) with examples of how to use clip options.

### clip_x

You can use clip options ([clip_x](#clip_x), [clip_y](#clip_y), [clip_width](#clip_width), [clip_height](#clip_height)) to clip only the part of the screen.

The `clip_x` option specifies only the top coordinate (x) of the area to clip.

### clip_y

You can use clip options ([clip_x](#clip_x), [clip_y](#clip_y), [clip_width](#clip_width), [clip_height](#clip_height)) to clip only the part of the screen.

The `clip_y` option specifies only the left coordinate (y) of the area to clip.

### clip_width

You can use clip options ([clip_x](#clip_x), [clip_y](#clip_y), [clip_width](#clip_width), [clip_height](#clip_height)) to clip only the part of the screen.

The `clip_width` option specifies only the width of the area to clip.

### clip_height

You can use clip options ([clip_x](#clip_x), [clip_y](#clip_y), [clip_width](#clip_width), [clip_height](#clip_height)) to clip only the part of the screen.

The `clip_height` option specifies only the width of the area to clip.

## Full page

Read more suggestions on [how to take better full-page screenshots](/docs/guides/full-page-screenshots/).

### full_page

To take the screenshot of the full page, set `full_page=true`.

Default value is `false`.

When `full_page` is set to `true`, [full_page_scroll](#full_page_scroll) is automatically set to `true`, until you override it. It is done to make sure that all lazy loaded images are requested and rendered.

An example of the request URL:

```
https://api.screenshotone.com/take?full_page=true&url=https://netflix.com&access_key=<your access key>
```

<Details>
    ![A full page screenshot of the Apple site taken by screenshot
    API](./full_page_example.png)
</Details>

### full_page_scroll

If set to `true`, scrolls to the bottom of the page and back to the top. Default value is `false`.

When `full_page` is set to `true`, `full_page_scroll` is automatically set to `true`, until you override it. It is done to make sure that all lazy loaded images are requested and rendered.

An example of the request URL:

```
https://api.screenshotone.com/take?full_page_scroll=true&full_page=true&url=https://netflix.com&access_key=<your access key>
```

### full_page_scroll_delay

The default value is `400` microseconds. Use it to specify how fast you want to scroll the page to the bottom.

Some sites require larger values than `400` microseconds to trigger the loading of lazy-load images.

Use it in combination with [full_page_scroll_delay](#full_page_scroll_by) to find optimal solution.

An example of the request URL:

```
https://api.screenshotone.com/take?full_page_scroll_delay=1000&full_page_scroll=true&full_page=true&url=https://netflix.com&access_key=<your access key>
```

### full_page_scroll_by

The default value is the height of the viewport. Use it to specify how fast you want to scroll the page to the bottom.

Some sites require values less than viewport height to trigger the loading of lazy-load images. Try to play with values between `100` and `500`. However, don't hesitate to try out any value that might work for you.

Use it in combination with [full_page_scroll_delay](#full_page_scroll_delay) to find optimal solution.

An example of the request URL:

```
https://api.screenshotone.com/take?full_page_scroll_by=400&full_page_scroll=true&full_page=true&url=https://netflix.com&access_key=<your access key>
```

### full_page_max_height

The default value is not set. Use it to limit the height of the full page screenshot. Also allows to handle
and fix problems related to infinite scrolling.

An example of the request URL:

```
https://api.screenshotone.com/take?full_page_max_height=10000&full_page_scroll=true&full_page=true&url=https://netflix.com&access_key=<your access key>
```

### full_page_algorithm

The default value is `default`. 

The `default` algorithm is the same as the one used in the Chrome DevTools Protocol, with some tuning and for some websites with different optimizations.

But if you set `full_page_algorithm=by_sections`, the API will take a screenshot section by section and then combine them into one image.
It allows more complex pages with animations to be rendered correctly.

The `by_sections` will scroll the website automatically regardless of the [full_page_scroll](#full_page_scroll) option value.

## Viewport

### viewport_device

**The default value is not set.**

Instead of manually specifying viewport parameters like width and height, you can specify a device to use for emulation. In addition, other parameters of the viewport, including the user agent, will be set automatically.

The `viewport_device` option sets the next options for you: [viewport_width](#viewport_width), [viewport_height](#viewport_height), [device_scale_factor](#device_scale_factor), [viewport_mobile](#viewport_mobile), [viewport_has_touch](#viewport_has_touch), [viewport_landscape](#viewport_landscape). You can change these options and override the ones set by the `viewport_device` option.

Use [the list of devices](/docs/viewport-devices/) for available values. Use the `id` property of the device as `viewport_device`, e.g. `viewport_device=galaxy_s9+_landscape`.

<Alert>
    API does not use an actual device to take a screenshot. It is emulation that
    works in most cases.
</Alert>

An example of the request URL with `viewport_device=iphone_13_pro_max_landscape`:

```
https://api.screenshotone.com/take?viewport_device=iphone_13_pro_max_landscape&url=https://tailwindcss.com&access_key=<your access key>
```

<Details>
    ![A screenshot of the Apple site taken by screenshot API for the specified
    device](./viewport_device_example.jpeg)
</Details>

### viewport_width

<Alert>
    If the [viewport_device](#viewport_device) option is set, the parameter
    overrides it!
</Alert>

The width of the browser viewport (pixels).

The browser's viewport is the window area where you can see the web content.

Default value is `1280`.

An example of the request URL with `viewport_width=1920` and `viewport_height=1080`:

```
https://api.screenshotone.com/take?viewport_width=1920&viewport_height=1080&url=https://apple.com&access_key=<your access key>
```

<Details>
    ![A full page screenshot of the Apple site taken by screenshot
    API](./viewport_width_and_height_example.png)
</Details>

### viewport_height

<Alert>
    If the [viewport_device](#viewport_device) option is set, the parameter
    overrides it!
</Alert>

The height of the browser viewport (pixels).

The browser's viewport is the window area where you can see the web content.

Default value is `1024`.

An example of the request URL with `viewport_width=1920` and `viewport_height=1080`:

```
https://api.screenshotone.com/take?viewport_width=1920&viewport_height=1080&url=https://apple.com&access_key=<your access key>
```

<Details>
    ![A full page screenshot of the Apple site taken by screenshot
    API](./viewport_width_and_height_example.png)
</Details>

### device_scale_factor

<Alert>
    If the [viewport_device](#viewport_device) option is set, the parameter
    overrides it!
</Alert>

Set the device scale factor, think of it as DPR (Device Pixel Ratio). The acceptable value is between the range of 1 and 5, including real numbers, like 2.25.

Set 2 if you need to render a screenshot with a higher pixel density like Apple's Retina Display.

The parameter can override the value set by [viewport_device](#viewport_device) option.

An example of the request URL with `device_scale_factor=1`:

```
https://api.screenshotone.com/take?device_scale_factor=1&url=https://apple.com&access_key=<your access key>
```

<Details>
    ![A full page screenshot of the Apple site taken by screenshot
    API](./device_scale_factor_1_example.png)
</Details>

An example of the request URL with `device_scale_factor=2`:

```
https://api.screenshotone.com/take?device_scale_factor=2&url=https://apple.com&access_key=<your access key>
```

<Details>
    ![A full page screenshot of the Apple site taken by screenshot
    API](./device_scale_factor_2_example.png)
</Details>

### viewport_mobile

<Alert>
    If the [viewport_device](#viewport_device) option is set, the parameter
    overrides it!
</Alert>

Whether the [meta viewport](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag) tag is taken into account. Defaults to `false`.

An example of the request URL with `viewport_mobile=true`:

```
https://api.screenshotone.com/take?viewport_mobile=true&url=https://example.com&access_key=<your access key>
```

### viewport_has_touch

<Alert>
    If the [viewport_device](#viewport_device) option is set, the parameter
    overrides it!
</Alert>

The default value is `false`. Set to `true` if the viewport supports touch events.

The parameter can override the value set by [viewport_device](#viewport_device) option.

An example of the request URL with `viewport_has_touch=true`:

```
https://api.screenshotone.com/take?viewport_has_touch=true&url=https://example.com&access_key=<your access key>
```

### viewport_landscape

<Alert>
    If the [viewport_device](#viewport_device) option is set, the parameter
    overrides it!
</Alert>

The default value is `false`. Set to `true` if the viewport is in landscape mode.

The parameter can override the value set by [viewport_device](#viewport_device) option.

An example of the request URL with `viewport_landscape=true`:

```
https://api.screenshotone.com/take?viewport_landscape=true&url=https://example.com&access_key=<your access key>
```

## Image

### image_quality

Render image with specified quality. Available for the next formats:

-   `jpeg` (`jpg`)
-   `webp`
-   `png`
-   `tiff`
-   `jp2`
-   `avif`
-   `hei`

Allowed range is between 0 and 100. Default value is `80`.

An example of the request URL with `image_quality=10`:

```
https://api.screenshotone.com/take?format=webp&image_quality=10&url=https://apple.com&access_key=<your access key>
```

<Details>
    ![A screenshot of the Apple site taken by screenshot
    API](./format_jpeg_low_quality_example.jpeg)
</Details>

### image_width

The `image_width` and `image_height` parameters allow you to create a thumbnail of the screenshot.

By default `image_width` = [viewport_width](#viewport_width) and `image_height` = [viewport_height](#viewport_height).

If you specify image width and height parameters, the API will resize a screenshot, preserving the aspect ratio. The image will be resized to be as large as possible while ensuring its dimensions are less than or equal to the image width and height specified.

If you omit one of the parameters, the other is computed automatically, preserving the aspect ratio.

An example of the request with `image_width=500`:

```
https://api.screenshotone.com/take?image_width=500&url=https://example.com/&access_key=<access key>
```

### image_height

The `image_width` and `image_height` parameters allow you to create a thumbnail of the screenshot.

By default `image_width` = [viewport_width](#viewport_width) and `image_height` = [viewport_height](#viewport_height).

If you specify image width and height parameters, the API will resize a screenshot, preserving the aspect ratio. The image will be resized to be as large as possible while ensuring its dimensions are less than or equal to the image width and height specified.

If you omit one of the parameters, the other is computed automatically, preserving the aspect ratio.

An example of the request with `image_width=500&image_height=400`:

```
https://api.screenshotone.com/take?image_width=500&image_height=400&url=https://example.com/&access_key=<access key>
```

### omit_background

Render a transparent background for the image. Works only if the site has not defined background color. Available for the following response formats:

-   `png`
-   `webp`

Default value is `false.

Set `omit_background=true` to take a screenshot with the transparent background.

## Emulations

### dark_mode

The default value is not set.

Set `true` to request site rendering, if supported, in the dark mode. Set `false` to request site rendering in the light mode if supported. If you don't set the parameter. The site is rendered in the default mode.

An example of the request URL with `dark_mode=true`:

```
https://api.screenshotone.com/take?dark_mode=true&url=https://tailwindcss.com/&access_key=<your access key>
```

<Details>
    ![A screenshot of the tailwindcss.com site taken by screenshot API in the
    dark mode](./tailwindcss.com_dark_mode.png)
</Details>

### reduced_motion

When `reduced_motion` set to `true`, the API will request the site to minimize the amount of non-essential motion it uses. When the site supports it, it should use animations as least as possible.

An example of the request URL with `reduced_motion=true`:

```
https://api.screenshotone.com/take?reduced_motion=true&url=https://tailwindcss.com/&access_key=<your access key>
```

### media_type

If you want to request the page and it is supported to be rendered for printers, specify `print`. If the page is by default rendered for printers and you want it to be rendered for screens, use `screen`.

An example of the request URL with `media_type=print`:

```
https://api.screenshotone.com/take?media_type=print&url=https://example.com/&access_key=<your access key>
```

## Customization

### hide_selectors

The `hide_selectors` option allows hiding elements before taking a screenshot. You can specify as many selectors as you wish. **All** elements that match each selector will be hidden by setting the `display` style property to `none !important`.

An example of the request URL with `hide_selectors=.a&hide_selectors=.b`:

```
https://api.screenshotone.com/take?hide_selectors=.a&hide_selectors=.b&url=https://example.com/&access_key=<your access key>
```

### scripts

`scripts` parameter allows to inject custom JavaScript and customize the page behavior.

An example of the request URL with `scripts=document.body.innerHTML="Hello, world!"`:

If the script might trigger a redirect by using window.location functions or something similar, it is required
to set [the "scripts_wait_until" option](#scripts_wait_until).

```
https://api.screenshotone.com/take?scripts=document.body.innerHTML="Hello,%20world!"&url=https://example.com/&access_key=<your access key>
```

<Details>
    ![A screenshot of the example.com site taken by screenshot
    API](./scripts_example.png)
</Details>

### scripts_wait_until

The default value of `scripts_wait_until` is `[]` — nothing, no wait at all.

The `scripts_wait_until` option allows you to wait until a given set of events after the [scripts](#scripts) were executed. You need to use in case, if your script might trigger page reloading, like:

```javascript
window.location = "https://example.com";
```

It accepts the same values as [wait_until](#wait_until) and can have multiple values:

-   `load`: the navigation is successful when the load even is fired;
-   `domcontentloaded`: the navigation is finished when the DOMContentLoaded even is fired;
-   `networkidle0`: the navigation is finished when there are no more than 0 network connections for at least 500 ms;
-   `networkidle2`: consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

The parameter accepts many values. It means that screenshots will be taken after all events occur altogether.

An example of the request with `scripts_wait_until=networkidle2&scripts_wait_until=domcontentloaded`:

```
https://api.screenshotone.com/take?scripts_wait_until=networkidle2&scripts_wait_until=domcontentloaded&url=https://example.com/&access_key=<access key>
```

### styles

`styles` parameter allows to inject custom styles and customize the page. It might help generate beautiful images for the Open Graph protocol.

An example of the request URL with `styles=h1{color: red;}`:

```
https://api.screenshotone.com/take?styles=h1{color:%20red;}&url=https://example.com/&access_key=<your access key>
```

<Details>
    ![A screenshot of the example.com site taken by screenshot
    API](./example_styles.png)
</Details>

<br />

A screenshot without styles for comparison:

<Details>
    ![A screenshot of the example.com site taken by screenshot
    API](./example_without_styles.png)
</Details>

### click

Specify the CSS selector of an element to click on before taking the screenshot. It could be anything, including a button, link, or even a regular `div` element.

Supports `shadow/` selectors which will traverse the shadow DOM elements. It will be slower, and if many elements have the same selectors, the first one will be chosen.

An example of the request URL with `click=.a-some-button-class-selector`:

```
https://api.screenshotone.com/take?click=.a-some-button-class-selector&url=https://example.com&access_key=<your access key>
```

### error_on_click_selector_not_found

If the element by selector to click is not visible or it took more than timeout seconds to render it, the error will be returned. Default value is `true`.

Set `error_on_click_selector_not_found=false` to do not throw an error if the element by selector is not found.

## Blocking

### block_cookie_banners

Blocks cookie banners, GDPR overlay windows, and other privacy-related notices. Default value is `false` when the `url` option is set.

It is useful when you want to take "clean" screenshots.

An example of the request URL with `block_cookie_banners=true`:

```
https://api.screenshotone.com/take?block_cookie_banners=true&url=https://stackoverflow.com&access_key=<your access key>
```

<Details>
    ![A screenshot of the StackOverflow site taken by screenshot
    API](./stackoverflow.com_without_cookie_banner.png)
</Details>

<br />

An example of the request URL with `block_cookie_banners=false`:

```
https://api.screenshotone.com/take?block_ads=false&url=https://stackoverflow.com&access_key=<your access key>
```

<Details>
    ![A screenshot of the StackOverflow site taken by screenshot
    API](./stackoverflow.com_with_cookie_banner.png)
</Details>

### block_banners_by_heuristics

<Alert>
    The option might be helpful if the regular
    [block_cookie_banners](#block_cookie_banners) option doesn't work. This
    parameter uses a different set of techniques and heuristics to block
    banners. But use it at your own risk. The site screenshot might not be
    precise with it.
</Alert>

Blocks cookie banners, GDPR overlay windows, and other privacy-related notices. Default value is `false`.

It is useful when you want to take "clean" screenshots, but the [block_cookie_banners](#block_cookie_banners) option doesn't work.

An example of the request URL with `block_banners_by_heuristics=true`:

```
https://api.screenshotone.com/take?block_banners_by_heuristics=true&url=https://example.com&access_key=<your access key>
```

### block_chats

Blocks chats like Crisp, Facebook Messenger, Intercom, Drift, Tawk, User.com, Zoho SalesIQ and many others. Default value is `false` when the `url` option is set..

It is useful when you want to take "clean" screenshots.

An example of the request URL with `block_chats=true`:

```
https://api.screenshotone.com/take?block_chats=true&url=https://screenshotone.com&access_key=<your access key>
```

<Details>
    ![A screenshot of the ScreenshotOne site taken by screenshot
    API](./without_chat_widget.png)
</Details>

<br />

An example of the request URL with `block_chats=false`:

```
https://api.screenshotone.com/take?block_chats=false&url=https://screenshotone.com&access_key=<your access key>
```

<Details>
    ![A screenshot of the ScreenshotOne site taken by screenshot
    API](./with_chat_widget.png)
</Details>

### block_ads

Blocks ads. Default value is `false` when the `url` option is set..

It is useful when you want to take "clean" screenshots or don't want to generate a loss for advertisers.

An example of the request URL with `block_ads=true`:

```
https://api.screenshotone.com/take?block_ads=true&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=<your access key>
```

<Details>
    ![A screenshot of the Scalable Developer site taken by screenshot
    API](./without_ads_example.png)
</Details>

<br />

An example of the request URL with `block_ads=false`:

```
https://api.screenshotone.com/take?block_ads=false&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=<your access key>
```

<Details>
    ![A screenshot of the Scalable Developer site taken by screenshot
    API](./with_ads_example.png)
</Details>

### block_trackers

Block trackers. Default value is `false` when the `url` option is set.

It is useful when you don't want to count screenshots as client visits in your analytics app.

Set `block_trackers=true` to disable all trackers.

### block_requests

Block requests by specifying URL, domain, or even a simple pattern like `block_requests=*.example.com/*`. You can specify the parameter multiple times like `block_requests=example.com&block_requests=http://*`.

Blocking requests by URL or domain can be used to test how the site responds when resources are not available. Or it might be used to speed up page loading.

Or, as an example, another way of blocking ads and trackers with `block_requests=*.carbonads.com&block_requests=*.google-analytics.com`:

```
https://api.screenshotone.com/take?block_requests=*.carbonads.com&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=<access key>
```

<Details>
    ![A screenshot of the Scalable Developer site taken by screenshot
    API](./without_ads_example.png)
</Details>

### block_resources

Blocks loading resources by type. Available resource types are:

-   `document`
-   `stylesheet`
-   `image`
-   `media`
-   `font`
-   `script`
-   `texttrack`
-   `xhr`
-   `fetch`
-   `eventsource`
-   `websocket`
-   `manifest`
-   `other`

Blocking resources might be helpful when you need to optimize page loading speed before taking a screenshot.

You can specify multiple values as `block_resources=stylesheet&block_resources=image`:

```
https://api.screenshotone.com/take?block_resources=stylesheet&block_resources=image&url=https://screenshotone.com&access_key=<access key>
```

<Details>
    ![A screenshot of the ScreenshotOne landing page site taken by screenshot
    API](./without_styles_and_images.png)
</Details>

## Geolocation

### geolocation_latitude

Set geolocation latitude for the request. Both latitude and longitude are required if one of them is set.

Take a screenshot from Eiffel Tower with accuracy in 50 meters `geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50`:

```
https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=<access key>
```

<Details>
    ![A screenshot from Eiffel Tower with accuracy in 50 meters taken by
    screenshot API](./eiffel_tower.png)
</Details>

### geolocation_longitude

Set geolocation longitude for the request. Both latitude and longitude are required if one of them is set.

Take a screenshot from Eiffel Tower with accuracy in 50 meters `geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50`:

```
https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=<access key>
```

<Details>
    ![A screenshot from Eiffel Tower with accuracy in 50 meters taken by
    screenshot API](./eiffel_tower.png)
</Details>

### geolocation_accuracy

Set the geolocation accuracy in meters.

Take a screenshot from Eiffel Tower with accuracy in 50 meters `geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50`:

```
https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=<access key>
```

<Details>
    ![A screenshot from Eiffel Tower with accuracy in 50 meters taken by
    screenshot API](./eiffel_tower.png)
</Details>

## Request

### ip_country_code

<Alert>If `proxy` is set, it overrides the `ip_country_code` option.</Alert>

You can use data center proxies provided by ScreenshotOne to take screenshots from different countries. Set parameter `ip_country_code`to the desired country, and you are ready to go, e.g., `ip_country_code=gb`.

The parameter is not supposed to be used for stealth screenshots. These are not residential proxies. If you have such a case, please, feel free to send the request to support@screenshotone.com.

While ScreenshotOne uses premium, highly available data center proxies, routing requests through them is slower than without a proxy. Try to avoid using the feature if you don't need it.

The list of supported countries:

-   `us` (United States) **default**
-   `gb` (Great Britain)
-   `de` (Germany)
-   `it` (Italy)
-   `fr` (France)
-   `cn` (China)
-   `ca` (Canada)
-   `es` (Spain)
-   `jp` (Japan)
-   `kr` (South Korea)
-   `in` (India)
-   `au` (Australia)
-   `br` (Brazil)
-   `mx` (Mexico)
-   `nz` (New Zealand)
-   `pe` (Peru)
-   `is` (Iceland)
-   `ie` (Ireland).

Feel free to request any additional country at support@screenshotone.com.

### proxy

<Alert>If `proxy` is set, it overrides the `ip_country_code` option.</Alert>

You can use your custom proxy to take screenshots or render HTML with the `proxy` option.

It is suitable in many cases. For example, you might want to render a screenshot from the given location and check how the site renders for this location.

Only the `HTTP` proxies are supported.

If you need to specify username and password, use the usual URL format like: http://myuser:mypassword@example.com/.

Example of the request:

```
https://api.screenshotone.com/take?proxy=http://127.0.0.1:1080&url=https://example.com/&access_key=<access key>
```

### user_agent

<Alert>
    ScreenshotOne takes care of the browser user agent, if you change the user agent, you might break stealth mode capabilities. 
    Change the user agent only when you absolutely need that and know what you are doing. 

    If the [viewport_device](#viewport_device) option is set, the parameter
    overrides it!
</Alert>

A user agent for the request. The default value is the latest version of the browser that `Puppeteer` uses.

An example with default user agent:

```
https://api.screenshotone.com/take?url=https://www.whatsmyua.info/&access_key=<access key>
```

<Details>
    ![A screenshot with default user agent by screenshot
    API](./default_user_agent.png)
</Details>

<br />{" "}

An example with specified user agent `user_agent=screenshoter`:

```
https://api.screenshotone.com/take?user_agent=screenshoter&url=https://www.whatsmyua.info/&access_key=<access key>
```

<Details>
    ![A screenshot with custom user agent by screenshot
    API](./screenshoter_user_agent.png)
</Details>

### authorization

Set the `Authorization` header for the request.

Setting the authorization header is proper when you want to take a screenshot of the protected page by basic authentication or token.

For example, if use basic authentication with credentials like `username:password`, encode it to Base64 format `dXNlcm5hbWU6cGFzc3dvcmQ=` and then use set the value of the authorization header like `authorization=Basic+dXNlcm5hbWU6cGFzc3dvcmQ=`.

Also, check our guide about [how to screenshot authenticated pages](/docs/guides/authenticated-pages/).

### cookies

Set cookies for the request in format `<cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly`. You can specify multiple cookies.

An escaped query string might look like:
`cookies=name1=val1;+Domain=example.com;+Secure;+HttpOnly&cookies=name2=val2;+Domain=example.com;+Secure;+HttpOnly`

### headers

Set extra headers for the request in the format of `Header-Name:Header-Value`

Headers can override all other previously implicitly set headers by options like `cookies` or `authorization`.

You can specify multiple headers at once `headers=X-Header-1:Value-1&headers=X-Header-2:Value-2`:

```
https://api.screenshotone.com/take?headers=X-Header-1:Value-1&headers=X-Header-2:Value-2&url=http://myhttpheader.com/&access_key=<access key>
```

<Details>
    ![A screenshot with custom headers by screenshot API](./custom_headers.png)
</Details>

### time_zone

Sets time zone for the request. Available time zones are:

-   `America/Belize`
-   `America/Cayman`
-   `America/Chicago`
-   `America/Costa_Rica`
-   `America/Denver`
-   `America/Edmonton`
-   `America/El_Salvador`
-   `America/Guatemala`
-   `America/Guayaquil`
-   `America/Hermosillo`
-   `America/Jamaica`
-   `America/Los_Angeles`
-   `America/Mexico_City`
-   `America/Nassau`
-   `America/New_York`
-   `America/Panama`
-   `America/Port-au-Prince`
-   `America/Santiago`
-   `America/Tegucigalpa`
-   `America/Tijuana`
-   `America/Toronto`
-   `America/Vancouver`
-   `America/Winnipeg`
-   `Asia/Kuala_Lumpur`
-   `Asia/Shanghai`
-   `Asia/Tashkent`
-   `Europe/Berlin`
-   `Europe/Kiev`
-   `Europe/Lisbon`
-   `Europe/London`
-   `Europe/Madrid`
-   `Pacific/Auckland`
-   `Pacific/Majuro`

Default time zone is `GMT +/- 00:00`.

An example with `time_zone=Europe/Madrid`:

```
https://api.screenshotone.com/take?time_zone=Europe/Madrid&url=https://whatismytimezone.com/&access_key=<access key>
```

<Details>
    ![A screenshot with custom time zone by screenshot
    API](./europe_madrid_time_zone.png)
</Details>

### bypass_csp

In rare cases, especially when you trying to add [custom scripts] to a website, you need to bypass the content security policies of the website. You need to simplify the set `bypass_csp` to `true`, by default it is `false`.

## Wait

These are one of the most tricky parameters when rendering screenshots of a site. Read on [how to wait until the page is ready](/blog/puppeteer-wait-until-the-page-is-ready/) if you are curious. Or use these `wait` options directly.

### wait_until

Use `wait_until` to wait until an event occurred before taking a screenshot or rendering HTML or PDF.

The default value of `wait_until` is `['load']`. Allowed values are:

-   `load`: the navigation is successful when the load even is fired;
-   `domcontentloaded`: the navigation is finished when the DOMContentLoaded even is fired;
-   `networkidle0`: the navigation is finished when there are no more than 0 network connections for at least 500 ms;
-   `networkidle2`: consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

The parameter accepts many values. It means that screenshots will be taken after all events occur altogether.

An example of the request with `wait_until=networkidle2&wait_until=domcontentloaded`:

```
https://api.screenshotone.com/take?wait_until=networkidle2&wait_until=domcontentloaded&url=https://example.com/&access_key=<access key>
```

### delay

Specify the `delay` option in seconds to wait before taking a screenshot or rendering HTML or PDF.

It is suitable when the [wait_until](#wait_until) option does not work well for you, and you want to ensure that everything is ready.

The default value is 0.

The delay value can be more than 30 seconds, only if [the timeout option](#timeout) is larger than 300 seconds which is only allowed for asynchronous requests.

An example of the request with `delay=5`:

```
https://api.screenshotone.com/take?delay=5&url=https://example.com/&access_key=<access key>
```

### timeout

Specify `timeout` (in seconds) of when to abort the request if screenshot or rendering is still impossible. The default value is `60` seconds and the max value is `90`.

An example of the request with `timeout=20`:

```
https://api.screenshotone.com/take?timeout=20&url=https://example.com/&access_key=<access key>
```

### navigation_timeout

Specify `navigation_timeout` (in seconds) of when to abort the request if the target site doesn't respond. The default and max value is `30`.

An example of the request with `navigation_timeout=20`:

```
https://api.screenshotone.com/take?navigation_timeout=20&url=https://example.com/&access_key=<access key>
```

### wait_for_selector

<Alert>
    If you are already screenshotting an element by the same selector, waiting
    for a selector is not effective and won't be used.
</Alert>

Specify `wait_for_selector` to wait until the element appears in DOM, which is not necessarily visible.

If you specify a few selectors separated by commas, it will be enough to wait for only one. To change the behavior and wait 
for all selectors, check out the [wait_for_selector_algorithm](#wait_for_selector_algorithm) option.

An example of the request with `wait_for_selector=.dynamically-loaded-element`:

```
https://api.screenshotone.com/take?wait_for_selector=.dynamically-loaded-element&url=https://example.com/&access_key=<access key>
```

### wait_for_selector_algorithm 

The default value is `at_least_one` that means to wait for at least one selector matched.

You can set it to `at_least_by_count` to wait for all selectors matched at least. But it doesn't mean all elements matched.

E.g. if you specify '.class1,.class2' and there are 2 elements in the DOM that match this selector, it will be enough to stop waiting. 
It can also mean that there are 2 elements of `.class1`.

## Caching

There is [a dedicated page about caching](/docs/caching/) and how to use it.

:::note
**Screenshots are not cached by default.**
:::

Screenshots are cached by the combination of all specified request options. And the [cache_key](#cache_key) option allows having different cached versions of the same screenshot.

Cached screenshots are not counted by quota and are not logged anywhere. They are served directly from the cache. Screenshots are cached in a combination of Cloudflare CDN and R2 storage (like Amazon S3).

There is a header `x-screenshotone-cache-url` that provides a direct link to the cached image, PDF or video. The file exist as long as it was defined in the [cache_ttl](#cache_ttl) parameter when API request was performed with `cache=true`.

And if the `response_type` option is specified as `json`, you can find a cache URL in the JSON response too:

```json
{
    "cache_url": "https://cache.screenshotone.com/..."
}
```

What is the benefits of using the cache URL?

1. You don't share API keys and don't complicate your code with [signed links](/docs/signed-requests/).
2. You control when to regenerate the cache, but a user with a link to the screenshot can't regenerate it. Because if you shared a link to an API request, once the cache is expired, it would be regenerated.

### cache

The `cache` option enables or disables caching of a screenshot, rendering HTML, or PDF. The default value is `false`.

The `false` option forces disabling caching and always generate a free screenshot or render HTML or PDF without caching.

An example of the request with `cache=false`:

```
https://api.screenshotone.com/take?cache=false&url=https://example.com/&access_key=<access key>
```

### cache_ttl

The `cache` option must be set to `true` to use the `cache_ttl` parameter.

The `cache_ttl` option (in seconds) hints at how long the cached screenshot should be stored. The minimum value is `14400` seconds (4 hours), and the maximum value is `2592000` seconds (one month).

An example of the request with `cache_ttl=20000`:

```
https://api.screenshotone.com/take?cache=true&cache_ttl=20000&url=https://example.com/&access_key=<access key>
```

### cache_key

The `cache` option must be set to `true` to use the `cache_key` parameter.

Screenshots are cached by the combination of all specified request options. The [cache_key](#cache_key) option allows having different cached versions of the same screenshot.

An example of the request with `cache_key=abc123`:

```
https://api.screenshotone.com/take?cache=true&cache_key=abc123&url=https://example.com/&access_key=<access key>
```

## Storing

<Alert>
    When the [cache option](#cache) is set to true, the upload will be triggered
    only on the cache miss. It means that if you want to upload screenshots
    anytime, you take them, please set the [cache option](#cache) to false.
</Alert>

You can use any S3-compatible storage to store screenshots,
rendered HTML or PDF to the configured S3 bucket.

In case you don't care about getting the actual but only want to upload the rendering result to storage, specify [response_type=empty](#response_type).

An example of the request with `response_type=empty`:

```
https://api.screenshotone.com/take?response_type=empty&url=https://example.com/&access_key=<access key>
```

### store

Default value is `false`. Use `store=true` to trigger upload of the taken screenshot, rendered HTML or
PDF to the configured S3 bucket. Make sure you configured [access to S3](https://dash.screenshotone.com/access).

An example of the request with `store=true`:

```
https://api.screenshotone.com/take?store=true&url=https://example.com/&access_key=<access key>
```

### storage_path

The parameter is required if you set `store=true`. You must specify the key for the file, but don't
specify an extension, it will be added automatically based on the [format](#format) you specified.

You can also specify "subdirectories" in the path part.

An example of the request with `storage_path=latest/example`:

```
https://api.screenshotone.com/take?store=true&storage_path=latest/example&url=https://example.com/&access_key=<access key>
```

### storage_endpoint

Leave empty for Amazon S3, specify only when needed. Any S3-compatible storage is supported, e.g. `"https://<accountId>.r2.cloudflarestorage.com"` for Cloudlfare R2 storage.

### storage_access_key_id

Access key ID. It overrides the one specified in the dashboard configuration.

### storage_secret_access_key

Secret access key. It overrides the one specified in the dashboard configuration.

### storage_bucket

You can override the default bucket you configured with `storage_bucket=<bucket name>`.

An example of the request with `storage_bucket=temporary`:

```
https://api.screenshotone.com/take?storage_bucket=temporary&store=true&storage_path=latest/example&url=https://example.com/&access_key=<access key>
```

### storage_class

The default value is `standard`.

Storage class allows you to specify [the object storage class](https://aws.amazon.com/s3/storage-classes/).

Allowed values:

-   `standard`;
-   `reduced_redundancy`;
-   `standard_ia`;
-   `onezone_ia`;
-   `intelligent_tiering`;
-   `glacier`;
-   `deep_archive`;
-   `outposts`;
-   `glacier_ir`.

An example of the request with `storage_class=glacier_ir`:

```
https://api.screenshotone.com/take?storage_class=glacier_ir&store=true&storage_path=latest/example&url=https://example.com/&access_key=<access key>
```

### storage_acl

The default value is not set.

Specify [the ACL value](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl) when uploading the file.

Allowed values:

-   (not set) (**default**);
-   `public-read`.

An example of the request with `storage_acl=public-read`:

```
https://api.screenshotone.com/take?storage_acl=public-read&store=true&storage_path=latest/example&url=https://example.com/&access_key=<access key>
```

### storage_return_location

You can require to return the file location returned by S3.

An example of the request with `storage_return_location=true`:

```
https://api.screenshotone.com/take?storage_return_location=true&store=true&storage_path=latest/example&url=https://example.com/&access_key=<access key>
```

You will receive the location as a header `X-ScreenshotOne-Store-Location` or if you set `response_type=json` as a property of JSON `store.location`.

## Metadata

You can extract different properties of the site or a screenshot on demand. They might impact performance, and that's why they are disabled by default.

### metadata_image_size

The default value is `false`.

Set to `true` to get the screenshot's actual image width and height. If response_type is set to `json`, you can get it from `metadata.image_size{width,height}` property. Otherwise, read from response headers such as `X-ScreenshotOne-Image-Width` and `X-ScreenshotOne-Image-Height`.

### metadata_fonts

The default value is `false`.

Get the fonts used by a website.

### metadata_icon

Get the favicon used by a website.

The default value is `false`.

```
https://api.screenshotone.com/take?metadata_icon=true&url=https://screenshotone.com/&access_key=<access key>
```
As headers: 

```
X-ScreenshotOne-Icon: {"url":"https://screenshotone.com/favicon-32x32.png","type":"image/png"}
```

As JSON:
```json
{
    "metadata": {
        "icon": {
            "url": "https://screenshotone.com/favicon-32x32.png",
            "type": "image/png"
        }
    }
}
```

:::danger
Do not render the icon from the URL directly in your web application, it might be used to attack your site, always check and sanitize it.

Also, sometimes, it can return data URLs for the icon URL, like: `data:image/svg+xml,<svg...`.
:::

### metadata_open_graph

The default value is `false`.

If you set it to `true`, you can get the parsed Open Graph metadata either in the `x-screenshotone-open-graph` header, or in the JSON as the `metadata.open_graph` property.

```json
{
    "metadata": {
        "open_graph": {
            "title": "The Screenshot API for developers",
            "description": "ScreenshotOne is the best screenshot rendering platform for developers.",
            "image": "https://screenshotone.com/og.png"
        }
    }
}
```

### metadata_page_title

The default value is `false`.

Get the title of the page.

Either in the `x-screenshotone-page-title` header, or in the JSON as the `metadata.page_title` property.

### metadata_content

You can request the content (HTML) of the page in addition to the screenshot. It will be uploaded to the ScreenshotOne CDN/public storage and you will receive the URL of the content and the date when it expires and is not available anymore.

If you don't use caching, then the API will use the minimum available [cache TTL](https://screenshotone.com/docs/options/#cache_ttl). Don't expect content URLs to be permanent and download the content as early and as fast as you can.

If the content is successfully extracted and uploaded, you will get the URL of the file in the header as `X-ScreenshotOne-Content-URL`. Also `X-ScreenshotOne-Content-Expires` header with the value when the content won't be available. The format of the expires header is the same as for the regular [Expires HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires).

If you use JSON response type, then you will get it as:

```json
{
    // ...
    "content": {
        "url": "https://example.com/...",
        "expires": "Wed, 21 Oct 2015 07:28:00 GMT"
    }
    // ...
}
```

On rare occasions if there is an error or some problem of fetching HTML content of the page, you won't get that data, then it is recommended to perform one more request but use [an HTML format instead](https://screenshotone.com/docs/options/#format).

The default value is `false`.

Consider including the shadow DOM elements with the [`include_shadow_dom`](#include_shadow_dom) option.

### metadata_content_format

You can specify the format of the page content when using the [`metadata_content`](#metadata_content) option.

Available formats:
- `html` - returns the HTML content of the page (default);
- `markdown` - returns the page content converted to `Markdown` format.

```
https://api.screenshotone.com/take?response_type=json&metadata_content=true&metadata_content_format=markdown&url=https://example.com/&access_key=<your access key>
```

If you use JSON response type, you will get:

```json
{
    "content": {
        "url": "https://example.com/...",
        "expires": "Wed, 21 Oct 2015 07:28:00 GMT",
        "format": "markdown"
    }
}
```

The default value is `html`.

### metadata_http_response_status_code

Set to `true` to get the host HTTP response headers.

If you render a binary screenshot, not JSON, you can get that data from the API response headers as `X-ScreenshotOne-HTTP-Response-Status-Code`.

In JSON, it will look like: 

```json
https://api.screenshotone.com/take?
&url=https://example.com/
...
&metadata_http_response_headers=true
&metadata_http_response_status_code=true

{
    ...
    "http_response": {
      "status_code": 200,
      "headers": {
        "accept-ranges": "bytes",
        "age": "56658",
        "cache-control": "max-age=604800",
        "content-encoding": "gzip",
        "content-length": "648",
        "content-type": "text/html; charset=UTF-8",
        "date": "Fri, 02 Aug 2024 10:26:35 GMT",
        "etag": "\"3147526947\"",
        "expires": "Fri, 09 Aug 2024 10:26:35 GMT",
        "last-modified": "Thu, 17 Oct 2019 07:18:26 GMT",
        "server": "ECAcc (nyd/D13E)",
        "vary": "Accept-Encoding",
        "x-cache": "HIT"
      }
    }
    ...
}
```

### metadata_http_response_status_headers

Set to `true` to get the host HTTP response status code.

If you render a binary screenshot, not JSON, you can get that data from the API response headers as `X-ScreenshotOne-HTTP-Response-Headers`.

In JSON, it will look like: 

```json
https://api.screenshotone.com/take?
&url=https://example.com/
...
&metadata_http_response_headers=true
&metadata_http_response_status_code=true

{
    ...
    "http_response": {
      "status_code": 200,
      "headers": {
        "accept-ranges": "bytes",
        "age": "56658",
        "cache-control": "max-age=604800",
        "content-encoding": "gzip",
        "content-length": "648",
        "content-type": "text/html; charset=UTF-8",
        "date": "Fri, 02 Aug 2024 10:26:35 GMT",
        "etag": "\"3147526947\"",
        "expires": "Fri, 09 Aug 2024 10:26:35 GMT",
        "last-modified": "Thu, 17 Oct 2019 07:18:26 GMT",
        "server": "ECAcc (nyd/D13E)",
        "vary": "Accept-Encoding",
        "x-cache": "HIT"
      }
    }
    ...
}
```

## Async and Webhooks

There is a [complete guide about asynchronous requests and webhooks](/docs/async-and-webhooks/).

### async

You can execute any request asynchronously by setting the `async` option to `true`. The API will return an empty response immediately. It is `false` by default.

Usually, it is in [combination with webhooks](/docs/async-and-webhooks/) to [upload rendered screenshots or PDFs to S3](/docs/upload-to-s3/).

### webhook_url

You can receive the result of the screenshot execution at your desired URL. To do it, specify the `webhook_url` parameter. E.g. `webhook_url=https://example.com`.

Usually, it is in [combination with async](/docs/async-and-webhooks/) to [upload rendered screenshots or PDFs to S3](/docs/upload-to-s3/).

### webhook_sign

Signing webhook request body takes time. If you are sure that your webhooks are unique and secret, you might want to disable signing to improve performance by using `webhook_sign=false`.

It is `true` by default.

### webhook_errors

Set to `true` to get the error details in the webhook request body (if JSON response type is used) or headers.

It is `false` by default.

## Error options

### ignore_host_errors

When the site responds within the range of 200-299 status code, you can ignore errors and take a screenshot of the error page anyway. To do that, set the option `ignore_host_errors` to true. It is `false` by default.

It is helpful when you want to create a gallery of error pages or, for some reason, you need to render error pages.

### error_on_selector_not_found

If [a selector](#selector) or a [scroll_into_view option](#scroll_into_view) is specified and `error_on_selector_not_found=true`, the error will be returned if the element by selector is not visible or it took more than `timeout` seconds to render it, but not more than 30 seconds.

Default value is `false`.

### fail_if_request_failed

The option forces the request to fail if any network request fails during page loading. By default, it is not specified, which means the screenshot will be taken even if some resources (like images, scripts, or stylesheets) fail to load.

Setting `fail_if_request_failed` is useful when you need to ensure that all resources are properly loaded before taking a screenshot. This can help identify issues with missing assets or network problems.


An example of the API request that will fail if any request URL that matches *example.com* fails:

```
https://api.screenshotone.com/take?access_key=<access key>&fail_if_request_failed=*example.com*&url=https://example.com/
```

Failed requests are not counted against your rendering quota.

### fail_if_content_missing

The option forces the request to fail if the specified text is missing on the page content. Case insensitive.

It can be specified multiple times. And the request will fail if any of the specified strings is missing on the page content.

Failed requests are not counted against your rendering quota.

### fail_if_content_contains

The option forces the request to fail if the specified text is matched on the page content. Case insensitive.

It can be specified multiple times. And the request will fail if any of the specified strings is matched on the page content.

Check out the guide on [how to fail rendering if the content contains a string](/docs/guides/fail-if-content-contains/) for more details.

Failed requests are not counted against your rendering quota.

### fail_if_gpu_rendering_fails

The options forces the request to fail if GPU rendering fails. Otherwise, the request will be retried. Or sent to the CPU-based rendering services.

# How to render Google Slides as scrolling screenshots with ScreenshotOne

import Video from "@/components/Video.astro";

By default, you can not render Google Slides as scrolling screenshots with the ScreenshotOne API. But if you managed to export it as HTML, you can make it work.

## Make Google Slides available as HTML

To make Google Slides available as HTML, you need to export it as HTML from the Google Slides editor.

I created [a simple example Google Slides presentation](https://docs.google.com/presentation/d/1fsaM1LaLUEzNn9pTPRdY0XBz1WxaFcWBD2WY50SrqwY/edit?usp=sharing) to demonstrate how to do that.

(1) For you presentation, go to share settings: 

![The Google Slides share settings](./google-slides-share-settings.png)

(2) Change the settings to make the presentation public and shareable:

![The Google Slides share settings](./google-slides-share-settings-make-public.png)

After that you can use either Google Slides API or make the link shareable and public to everyone and then modify it to the link like:
`https://docs.google.com/presentation/d/<presentation id>/export/html`

## Render Google Slides as scrolling screenshots

Get your ScreenshotOne API key at the [ScreenshotOne dashboard](https://dashboard.screenshotone.com/).

And then implement the following example in TypeScript or any other language you want:

```typescript
// validate URL
const presentationUrl = new URL(url);
if (!presentationUrl.hostname.includes("docs.google.com")) {
    throw new Error("Invalid URL: Must be a Google Slides presentation URL");
}

// Extract presentation ID from the Google Slides URL
const match = presentationUrl.pathname.match(/presentation\/d\/([\w-]+)/);
if (!match) {
    throw new Error("Invalid Google Slides URL format");
}

const presentationId = match[1];
const exportUrl = `https://docs.google.com/presentation/d/${presentationId}/export/html`;
url = exportUrl;

// Prepare ScreenshotOne API parameters
const params: Record<string, string> = {
    url: url,
    access_key: SCREENSHOTONE_ACCESS_KEY as string,
    format: "mp4",
    scenario: "scroll",
    delay: "2", // wait for 2 seconds before starting to scroll
};

const apiUrl = `https://api.screenshotone.com/animate`;
console.log("Making request to ScreenshotOne API...");

// Make request to ScreenshotOne API
const screenshotResponse = await axios({
    method: "post",
    url: apiUrl,
    data: params,
    headers: {
        "Content-Type": "application/json",
    },
    responseType: "stream",
    maxContentLength: Infinity,
    maxBodyLength: Infinity,
    timeout: 60000, // increase timeout to 60 seconds
});

// Process the video
```

Notice that we use a POST HTTP request to the `https://api.screenshotone.com/animate` endpoint. It is good if you want to send HTML yourself, but also works with URLs. Also, you can just send a regular GET request.

The resulting video will be something like: 

<Video url="/videos/google-slides-scrolling-screenshot.mp4" />

## Custom styles 

You can set custom styles via the `style` option:

```
style=<your CSS styles>
```

## A working example

You can find a fully working example (written in Node.js/TypeScript) in the [ScreenshoOne integration examples directory](https://github.com/screenshotone/examples/tree/main/nodejs/google-slides-scrolling-screenshots). However, it downloads HTML to render it with ScreenshotOne, but today you do not need that, you can render Google Documents and Slides directly with ScreenshotOne.

## Suggestions

1. If possible, use the official Google Slides API to get the HTML. It is more reliable and easier to use. 
2. If you build this solution for third-party use, consider if you can automate the processing of authentication with Google Slides and extract the HTML. 

## Google Documents

Check out [our guide on how to render Google Documents as screenshots](/docs/guides/screenshot-google-docs/).

## Support 

In case you have any questions or suggestions, feel free to reach out at `support@screenshotone.com`.

# How to screenshot an area of a site

import Alert from "@/components/Alert.astro";

When rendering website screenshots with the ScreenshotOne Screenshot API, you can specify [clip options](https://screenshotone.com/docs/options/#clip) to render only a specific area of the website.

<Alert>You must specify all clip options, otherwise, it won't work.</Alert>

For example, let's clip a square of the ScreenshotOne landing page:

```
https://api.screenshotone.com/take?access_key=<your api key>&url=https://screenshotone.com&clip_x=100&clip_y=100&clip_width=500&clip_height=500
```

The resulting image will be:

![A clip example](./clip_example.png)

In case you can rely on a selector, it is better to use [the selector option](https://screenshotone.com/docs/options/#selector) than precise coordinates. It will allow you to produce more stable results. But in case you know what you do and prefer to rely on specific coordinates, it is OK to use clip options.

A few typical uses of the feature:

1. **Content Monitoring**. Businesses can use this feature to monitor their website's content regularly, ensuring that updates are correctly deployed and that there are no visual anomalies or layout issues.

2. **Competitor Analysis**. Companies can clip and analyze key sections of competitors' websites, such as product pages or promotional banners, to stay informed about market trends and competitor strategies.

3. **QA Testing**. Web developers and QA teams can automate the process of taking screenshots of different sections of a webpage across various devices and browsers for testing purposes, ensuring consistency and identifying layout issues.

Enjoy it. If you have any questions, please, feel free to send an email to `support.screenshotone.com`.

# Notifications

When you reach 90% or 100% of your screenshot limit, you will receive a notification to your email and/or Slack.

## Email

By default, you will receive an email notification when you reach 90% or 100% of your screenshot limit. You can disable these notifications in the [dashboard](https://dash.screenshotone.com/notifications), but they are enabled by default:

![Email notifications](./notifications.png)

## Slack

You can also enable Slack notifications in the [dashboard](https://dash.screenshotone.com/notifications), in addition to the email notifications.

To enable Slack notifications, you need to specify a Slack webhook URL in the [dashboard](https://dash.screenshotone.com/notifications):

![Slack notifications](./slack-webhook-url-input.png)

To configure a Slack webhook URL, you need to create a new webhook in your Slack workspace.

### 1. Create a Slack application

[Create a new Slack application](https://api.slack.com/apps/new).

![Create a Slack application](./1-create-slack-app.png)

### 2. Enable incoming webhooks

Go to [your application settings](https://api.slack.com/apps) and enable incoming webhooks:

![Enable incoming webhooks](./2-enable-incoming-webhooks.png)

### 3. Add new webhook to your workspace

Click on the "Add New Webhook to Workspace" button:

![Add new webhook](./3-add-new-webhook-to-workspace.png)

And then choose the target channel:

![Incoming webhook channel](./3-incoming-webhook-channel.png)

### 4. Copy the webhook URL

![Copy webhook URL](./4-copy-webhook-url.png)

In this example, the webhook URL is:

```
https://hooks.slack.com/services/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
```

### 5. Save and test the webhook URL

Paste the webhook URL in the [dashboard](https://dash.screenshotone.com/notifications):

![Paste webhook URL](./5-paste-webhook-url.png)

And check the integration test message in the target channel:

![Integration test message](./6-check-integration-message.png)

### 6. Get notifications when you reach limits

Once you reach your limit, you will receive a notification in the target channel like this or similar:

![Limit example message](7-limit-example-message.png)

## Summary

These are the most important notifications you need to recieve from ScreenshotOne. If you have more ideas or issues with configuring or receiving notifications, please, reach out to us via `support@screenshotone.com`.

# Usage Quota Exceeded

It is an API error returned when the monthly usage quota has been exceeded:

```json
{
    "is_successful": false,
    "error_code": "screenshots_limit_reached",
    "error_message": "The usage quota has been exceeded. Please, either upgrade to a plan with more quota or change the maximum allowed limit (if possible) in the ScreenshotOne dashboard. If it is a mistake, please, reach out at `support@screenshotone.com.`",
    "documentation_url": "https://screenshotone.com/docs/usage-quota-exceeded/"
}
```

## Reasons and how to fix

There is a few ways on how to fix the error:

1. If you use a free plan, you need to upgrade to a paid plan. You can do that at [the Dashboard Billing page](https://dash.screenshotone.com/billing).
2. If you are already a paying customer, please, consider upgrade to a higher plan.
3. Or you can [request extra quota](/docs/charging-extra/).

## Reach out to support

If nothing helps you, please, reach out to `support@screenshotone.com` and we will try to help you as fast as possible.

# Storage Access Denied

It is an API error returned when the API can't upload a screenshot your S3 storage because the access is denined:

```json
{
    "is_successful": false,
    "error_message": "Failed to upload the screenshot to the storage since access was denied. Check the API keys you specify when using the storage integration.",
    "error_code": "storage_access_denied",
    "documentation_url": "https://screenshotone.com/docs/errors/storage-access-denied/"
}
```

## Reasons and how to fix

Let's quickly consider possible reasons and possible solutions.

### Perform configuration testing

In [the dashboard](https://dash.screenshotone.com/integrations/s3), you can test configuration and get the detailed error description:

![Configuration Testing](configuration_testing.jpg)

### Check credentials and URL

Make sure and double check that all your credentials and the storage URL is correct.

## Reach out to support

If nothing helps you, please, reach out to `support@screenshotone.com` and we will try to help you as fast as possible.

# JavaScript and TypeScript (Node.js) SDK and Code Examples

:::note
If you have any questions, please, reach out at `support@screenshotone.com`.
:::

### Installation

Run the next command to install the JavaScript and TypeScript Node.js SDK to take screenshots:

```shell
npm install screenshotone-api-sdk --save
```

### Usage

Don't forget to [sign up](https://dash.screenshotone.com/sign-up) to get access and secret keys.

:::danger
By default, the generated URL by SDK is not signed, and you can't share it,
because the API key will be leaked.

Use the method designated to generate a signed URL specifically—`generateSignedTakeURL()`.

Notice, in the recent versions of the SDK, all methods are asynchronous.
:::

Generate a screenshot URL without executing the request. Or download the screenshot. It is up to you:

```javascript
import * as fs from "fs";
import * as screenshotone from "screenshotone-api-sdk";

// create API client
const client = new screenshotone.Client("<access key>", "<secret key>");

// set up options
const options = screenshotone.TakeOptions.url("https://example.com")
    .delay(3)
    .blockAds(true);

// generate URL
const url = client.generateTakeURL(options); // or generateSignedTakeURL(options) for signed URLs
console.log(url);
// expected output: https://api.screenshotone.com/take?url=https%3A%2F%2Fexample.com&delay=3&block_ads=true&access_key=%3Caccess+key%3E

// or download the screenshot
const imageBlob = await client.take(options);
const buffer = Buffer.from(await imageBlob.arrayBuffer());
fs.writeFileSync("example.png", buffer);
// the screenshot is store in the example.png file
```

Check out [other SDKs and code examples](/docs/code-examples/).

# How to bypass CAPTCHAs

Since the the launch of ScreenshotOne API, it was designed to perform ethical screenshotting, hence the ScreenshotOne API doesn't support bypassing CAPTCHAs, by default.

However, if you need to do that, and you know what you are doing within the legal boundaries, you can use a third-party services as a proxy with ScreenshotOne API.

For, example [Web Unlocker by Bright Data](https://brightdata.com/products/web-unlocker) is a service that can be used to bypass CAPTCHAs as a proxy.

## Web Unlocker by Bright Data

:::danger

**Use it only as the last resort and if you are ready to pay for the increased usage of Web Unlocker.**

You will see increased usage of your requests for in your Web Unlocker account. One ScreenshotOne API request might be equal to 100-500 requests (sometimes even more) for the Web Unlocker proxy.

The Web Unlocker solution is not designed to work well with browser automation tools like the ScreenshotOne API uses. Cause every browser request is counted as a separate request for the Web Unlocker: loading images, CSS files, scripts and similar.

Prefer using the residential [proxies](/docs/guides/how-to-use-proxies/) if you need to bypass CAPTCHAs.
:::

The Web Unlocker by Bright Data is a great way to bypass CAPTCHAs if you need to. However, be aware that the API response time might be slower than the normal one, and sometimes the requests even might fail. It relates to how proxies operate and depends on the stability of the proxy provider.

[Brigh Data Web Unlocker](https://brightdata.com/products/web-unlocker) solution has `pay-as-you-go` pricing model, and it is a great way to bypass CAPTCHAs if you need to.

However, be aware that the API response time might be slower than the normal one, and sometimes the requests even might fail. It relates to how proxies operate and depends on the stability of the proxy provider.

### 1. Create the Web Unlocker proxy

To create the Web Unlocker proxy, sign up to [Bright Data](https://brightdata.com/), and once you log in, choose `Web Unlocker` from the "Add" menu:

![The Bright Data Dashboard](dashboard.png)

Make sure to enable the CAPTCHA solver and premium domains if needed:

![The Web Unlocker creation screen](create.png)

Once created, you can choose the Node.js code example and copy the proxy URL:

![The Web Unlocker code example](proxy_url.png)

### 2. Use the Web Unlocker proxy with the ScreenshotOne API

In this example, the proxy URL is:

```
http://brd-customer-hl_99a0bd97-zone-your_unlocker_name:can1v3iuf18x@brd.superproxy.io:22225

```

Now, you can use this proxy URL in the ScreenshotOne API request:

```
https://api.screenshotone.com/take?key=<YOUR API KEY>&url=https://example.com&proxy=http://brd-customer-hl_99a0bd97-zone-your_unlocker_name:can1v3iuf18x@brd.superproxy.io:22225
```

## Residential proxies

It is worth to mention, that using residential proxies might also prevent CAPTCHAs from even showing up. Check out our guide on [how to use proxies](/docs/guides/how-to-use-proxies) to learn more.

It happens because with the residential IP addresses, usually there is no need to even show CAPTCHAs, since it looks like that the requests are coming from real users, not bots.

## Cost optimizations

To save money on proxies, you can try to use the option [fail_if_content_contains](/docs/options/#fail_if_content_contains) to fail the request if the content contains a certain string that might hint you that there is a CAPTCHA on the page.

The option returns a specific error code like: 
```
{
    "is_successful": false,
    "error_code": "content_contains_specified_string",
    "error_message": "The page content contains the specified string by the `fail_if_content_contains` option. If it seems to be a mistake or not what you expected, please, reach out to `support@screenshotone.com` as quickly as possible, and we will assist and try to resolve your problem.",
    "documentation_url": "https://screenshotone.com/docs/errors/content-contains-specified-string/"
}
```

Since you don't pay for the failed requests, you can only then retry the request with the same parameters, but with the proxy that bypasses CAPTCHAs.

## Any questions?

Read more about [how to use proxies](/docs/guides/how-to-use-proxies) in the ScreenshotOne API and if you have any questions, feel free to reach out to us at [support@screenshotone.com](mailto:support@screenshotone.com).

# Fail rendering if the content contains a string

There is a set of use cases when you want to fail screenshot rendering and retry it if the content of the page contains a string.

For example, if you use residential rotating proxies and a site blocks you with some specific test, you might want to retry the request instead of getting the successful screenshot of the page with the CAPTCHA or an error.

:::tip[Did you know?]
You don't pay for failed and cached screenshots with ScreenshotOne.
:::

That's exactly what you need the option `fail_if_content_contains` for.

Let's quickly see how it works and how you can use it. Let's first render the example.com page:

```
https://api.screenshotone.com/take?access_key=<your access key>&url=https://example.com
```

The result is:

![The example.com website](example.com.png)

Now, let's try to fail it:

```
https://api.screenshotone.com/take?fail_if_content_contains=Illustrative+Examples+In+Documents&access_key=<your access key>&url=https://example.com
```

The result is:

```json
{
    "is_successful": false,
    "error_message": "The page content contains the specified string by the `fail_if_content_contains` option. If it seems to be a mistake or not what you expected, please, reach out to `support@screenshotone.com` as quickly as possible, and will assist and try to resolve your problem.",
    "error_code": "content_contains_specified_string",
    "documentation_url": "https://screenshotone.com/docs/errors/content-contains-specified-string/"
}
```

As you might notice, the match is case insensitive, it is done for simplicity.

You can also specify multiple strings to fail if any of them is matched on the page content:

```
https://api.screenshotone.com/take?fail_if_content_contains=Prior&fail_if_content_contains=Example&access_key=<your access key>&url=https://example.com
```

## A few more similar options

Check out the other similar options:

- [Fail rendering if the content is missing a string](/docs/options/#fail_if_content_missing)
- [Fail rendering if the request fails](/docs/options/#fail_if_request_failed)

## Support

If you have any questions or need help, please, reach out to `support@screenshotone.com` as quickly as possible, and we will assist and try to resolve your problem.

# How to render screenshots with different emoji styles

It might happen that you need to render screenshots with different emoji styles rather than the default emoji style provided by the ScreenshotOne API.

There are many emoji libraries out there that can help. For example, [emoji-js](https://www.npmjs.com/package/emoji-js) is a popular library that can be used to render emojis in different styles.

:::note
Whatever library you decided to use, or whatever emoji style you decided to use, make sure you do not violate any license of the emoji set you are using.

E.g. if you use [emojis provided by Twitter](https://github.com/twitter/twemoji), you must follow their license requirements.
:::

You can use it to replace emojis in the page with the desired style. E.g. you can replace all emojis with the emojis that look like Twitter emojis:

```js
const stylesheet = document.createElement("link");
stylesheet.href = "https://cdn.jsdelivr.net/npm/emoji-js@3.8.1/lib/emoji.min.css";
stylesheet.rel = "stylesheet";
document.head.appendChild(stylesheet);

const script = document.createElement("script");
script.onload = () => {
    // change to one you are interested in,
    // check the library documentation for the list of available emoji sets
    const img_set = "apple";

    const emoji = new window.EmojiConvertor();

    emoji.img_sets[img_set].path =
        `https://cdn.jsdelivr.net/npm/emoji-datasource-${img_set}@15.1.2/img/${img_set}/64/`;
    emoji.img_sets[img_set].sheet =
        `https://cdn.jsdelivr.net/npm/emoji-datasource-${img_set}@15.1.2/img/${img_set}/sheets/64.png`;
    emoji.img_set = img_set;

    emoji.replace_mode = "img";

    function replaceEmojisInTextNodes(node) {
        if (node.nodeType === Node.TEXT_NODE) {
            if (node.textContent && node.textContent.trim()) {
                const span = document.createElement("span");
                const replaced = emoji.replace_unified(node.textContent);
                span.innerHTML = replaced;

                if (replaced.trim() !== node.textContent.trim()) {
                    const parent = node.parentNode;
                    if (parent) {
                        while (span.firstChild) {
                            parent.insertBefore(span.firstChild, node);
                        }
                        parent.removeChild(node);
                    }
                }
            }
        } else if (node.nodeType === Node.ELEMENT_NODE) {
            if (node.tagName === "SCRIPT" || node.tagName === "STYLE") {
                return;
            }

            const childNodes = Array.from(node.childNodes);
            childNodes.forEach((child) => replaceEmojisInTextNodes(child));
        }
    }

    replaceEmojisInTextNodes(document.body);
};

script.src = "https://cdn.jsdelivr.net/npm/emoji-js@3.8.1/lib/emoji.min.js";
script.crossOrigin = "anonymous";

document.body.appendChild(script);
```

To use this script with the ScreenshotOne API, you can use `scripts` parameter to pass a script that will be executed on the page after it is loaded, and it will be rendered in the screenshot:

```
https://api.screenshotone.com/take?access_key=<your_access_key>&url=<your_url>&scripts=<your_script>
```

Where `<your_script>` is the URL-encoded script above.

E.g. like this:

```
https://api.screenshotone.com/take?access_key=<your_access_key>&url=https://example.com&scripts=const%20stylesheet%20%3D%20document.createElement%28%27link%27%29%3B%0Astylesheet.href%20%3D%20%27https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Femoji-js%403.8.1%2Flib%2Femoji.min.css%27%3B%0Astylesheet.rel%20%3D%20%27stylesheet%27%3B%0Adocument.head.appendChild%28stylesheet%29%3B%0A%0Aconst%20script%20%3D%20document.createElement%28%27script%27%29%3B%0Ascript.onload%20%3D%20%28%29%20%3D%3E%20%7B%0A%20%20%20%20%2F%2F%20change%20to%20one%20you%20are%20interested%20in%2C%20%0A%20%20%20%20%2F%2F%20check%20the%20library%20documentation%20for%20the%20list%20of%20available%20emoji%20sets%0A%20%20%20%20const%20img_set%20%3D%20%27apple%27%3B%0A%0A%20%20%20%20const%20emoji%20%3D%20new%20window.EmojiConvertor%28%29%3B%20%20%20%20%0A%20%20%20%20%0A%20%20%20%20emoji.img_sets%5Bimg_set%5D.path%20%3D%20%60https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Femoji-datasource-%24%7Bimg_set%7D%4015.1.2%2Fimg%2F%24%7Bimg_set%7D%2F64%2F%60%3B%0A%20%20%20%20emoji.img_sets%5Bimg_set%5D.sheet%20%3D%20%60https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Femoji-datasource-%24%7Bimg_set%7D%4015.1.2%2Fimg%2F%24%7Bimg_set%7D%2Fsheets%2F64.png%60%3B%0A%20%20%20%20emoji.img_set%20%3D%20img_set%3B%0A%0A%20%20%20%20emoji.replace_mode%20%3D%20%27img%27%3B%0A%0A%20%20%20%20function%20replaceEmojisInTextNodes%28node%29%20%7B%0A%20%20%20%20%20%20%20%20if%20%28node.nodeType%20%3D%3D%3D%20Node.TEXT_NODE%29%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20if%20%28node.textContent%20%26%26%20node.textContent.trim%28%29%29%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20const%20span%20%3D%20document.createElement%28%27span%27%29%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20const%20replaced%20%3D%20emoji.replace_unified%28node.textContent%29%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20span.innerHTML%20%3D%20replaced%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20if%20%28replaced.trim%28%29%20%21%3D%3D%20node.textContent.trim%28%29%29%20%7B%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20const%20parent%20%3D%20node.parentNode%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20if%20%28parent%29%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20while%20%28span.firstChild%29%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20parent.insertBefore%28span.firstChild%2C%20node%29%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20parent.removeChild%28node%29%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%20else%20if%20%28node.nodeType%20%3D%3D%3D%20Node.ELEMENT_NODE%29%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20if%20%28node.tagName%20%3D%3D%3D%20%27SCRIPT%27%20%7C%7C%20node.tagName%20%3D%3D%3D%20%27STYLE%27%29%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20return%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%0A%20%20%20%20%20%20%20%20%20%20%20%20const%20childNodes%20%3D%20Array.from%28node.childNodes%29%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20childNodes.forEach%28child%20%3D%3E%20replaceEmojisInTextNodes%28child%29%29%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%0A%20%20%20%20replaceEmojisInTextNodes%28document.body%29%3B%0A%7D%3B%0A%0Ascript.src%20%3D%20%27https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Femoji-js%403.8.1%2Flib%2Femoji.min.js%27%3B%0Ascript.crossOrigin%20%3D%20%27anonymous%27%3B%0A%0Adocument.body.appendChild%28script%29%3B
```

In case you have any issues, do not hesitate to reach out to us at support@screenshotone.com.

# How to translate and render a website as a screenshot

It is possible to translate and take a screenshot of the translated website with ScreenshotOne because the API supports scripts via the `scripts` option.

You can use any translation API of your choice. But as an example, in this guide, I will go with Google Translate API.

## Get your Google Translate API key

To get your Google API key:

1. Go to [the API credentials page in Google Cloud Platform](https://console.cloud.google.com/apis/credentials).
2. Generate your API key and make sure you restrict it to using only for Google Translate.
3. Make sure you set budgets, and notifications, and follow other [best practices](https://cloud.google.com/blog/products/ai-machine-learning/four-best-practices-for-translating-your-website) for Google Translate.

## Write a script to translate your websites

You need to write a script that efficiently will check all text nodes on the website, batch them, and send requests efficiently to save your costs.

:::danger
Please, make sure to optimize the script for your use case and that it doesn't overuse your quota. It is an example script and ScreenshotOne is not responsible for you using it and causing any damage to your business by the script. Use it at your own risk.
:::

Here is an example script you can try and use as a basis, but I highly recommend writing yours for production and making sure it has retries and other necessary logic:

```javascript
const translateTextAsync = async (texts, targetLang, apiKey) => {
    const url = `https://translation.googleapis.com/language/translate/v2?key=${apiKey}`;
    const data = {
        q: texts,
        target: targetLang,
    };

    const response = await fetch(url, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(data),
    });

    if (!response.ok) throw new Error("Network response was not ok.");

    const json = await response.json();
    return json.data.translations.map((t) => t.translatedText);
};

const isVisible = (element) => {
    return element.offsetWidth > 0 && element.offsetHeight > 0;
};

const shouldTranslate = (node) => {
    return (
        node.nodeType === Node.TEXT_NODE &&
        node.nodeValue.trim() &&
        isVisible(node.parentElement) &&
        !isDescendantOf(node, ["script", "code"])
    );
};

const isDescendantOf = (node, tagNames) => {
    let parent = node.parentElement;
    while (parent && parent !== document.body) {
        if (tagNames.includes(parent.tagName.toLowerCase())) {
            return true;
        }
        parent = parent.parentElement;
    }
    return false;
};

const batchTranslate = async (nodes, targetLang, apiKey) => {
    let batch = [];
    let totalLength = 0;
    const results = [];

    for (const node of nodes) {
        const text = node.nodeValue.trim();
        if (text.length + totalLength > 5000 || batch.length >= 128) {
            // Translate current batch
            const translations = await translateTextAsync(
                batch,
                targetLang,
                apiKey
            );
            translations.forEach((translatedText, index) => {
                results.push({ node: nodes[index], translatedText });
            });

            // Reset for next batch
            batch = [text];
            totalLength = text.length;
        } else {
            batch.push(text);
            totalLength += text.length;
        }
    }

    // Translate remaining batch
    if (batch.length > 0) {
        const translations = await translateTextAsync(
            batch,
            targetLang,
            apiKey
        );
        translations.forEach((translatedText, index) => {
            results.push({
                node: nodes[nodes.length - batch.length + index],
                translatedText,
            });
        });
    }

    return results;
};

const translatePageContent = async (element, targetLang, apiKey) => {
    const textNodes = [];
    const walker = document.createTreeWalker(
        element,
        NodeFilter.SHOW_TEXT,
        {
            acceptNode: (node) => {
                return shouldTranslate(node)
                    ? NodeFilter.FILTER_ACCEPT
                    : NodeFilter.FILTER_REJECT;
            },
        },
        false
    );

    let node;
    while ((node = walker.nextNode())) {
        textNodes.push(node);
    }

    const translations = await batchTranslate(textNodes, targetLang, apiKey);
    translations.forEach(({ node, translatedText }) => {
        node.nodeValue = translatedText;
    });
};

// Replace with your actual API key
const apiKey = "<your API key>";
// Target language code (e.g., 'es' for Spanish)
const targetLang = "es";

translatePageContent(document.body, targetLang, apiKey)
    .then(() => console.log("Translation completed"))
    .catch((error) => console.error("Translation error:", error));
```

## Rendered translated websites

Once you have a working script, make sure you URL-encode it and then send it to ScreenshotOne when rendering a screenshot. You can use either POST or GET requests.

But in this example, I will share with you a GET request example:

```
https://api.screenshotone.com/take?access_key=<your API key>&url=https://example.com&scripts=<URL-encoded script>&delay=10
```

You can see the example.com website rendered in the Spanish language:

![The example.com website rendered in the Spanish language](example.com.spanish.jpeg)

I hope the guide helps you translate and render any HTML or website content, and have a nice day!

# Getting Started

You can use the API to generate invoices in PDF format for any given URL or HTML. Or make hundreds of screenshots of your site with different options to check that the site looks as expected.

Whatever use case you have, I get you covered. If there is a feature missing, please, contact me, and I will try to help you as fast as possible.

## First Touch 

ScreenshotOne API is straightforward to use. There is an example of an actual request to an API: 

```
GET https://api.screenshotone.com/take?url=https://apple.com&access_key=<access key>
```

The result is: 
![A screenshot of the Apple site](apple_screenshot.png)

[Sign up](https://dash.screenshotone.com/sign-up) to get the access key and start taking screenshots.

## Requests

ScreenshotOne API supports both GET and POST HTTP requests.

All requests are sent over HTTPS. HTTPS is a non-negotiable requirement to protect your privacy.

To take a screenshot of the site with GET HTTP request, send a request to:

```
https://api.screenshotone.com/take?[options]
```

Takes and returns a screenshot of the given site with specified [options](/docs/options).

If you send a POST HTTP request to take a screenshot, you should specify options as JSON in the body of the request:

```
POST https://api.screenshotone.com/take
Content-Type: application/json 
{
    ...[options]
}
```

### Access key 

You can specify the access key as part of `GET` parameters, `POST` `JSON` body, or as a header `X-Access-Key`. 

## Responses

The response format depends on the given options. You might request API to return an image of PNG type or raw HTML instead of rendering it.

API returns the `Content-Type` header set according to the relevant MIME type for the requested format in options. 

Since API returns binary in the data, you can safely put the request URL to ScreenshotOne API directly into the <img> and <meta> tags:

```
<img
  src="https://api.screenshotone.com/take?url=apple.com&access_key=<your access key>"
  alt="A screenshot of apple.com"
/>
```

## Errors

The request might return an error due to an internal error, invalid options or when the limit is reached. ScreenshotOne API follows the HTTP status code semantic and returns JSON in case of an error: 

```
GET https://api.screenshotone.com/?[options]

Content-Type: application/json
{
    "error": {
        "code": "an_error_code",
        "message": "An error message"
    }
}
```

The API will always return [a human-readable error message, error code, and suitable HTTP status code](/docs/errors).

# How to handle API errors

Error handling is an essential part of any high-quality application. Make sure you handle all errors returned by the ScreenshotOne API correctly and provide informative explanations to your customers or react to them accordingly.

## Following HTTP standards

The ScreenshotOne API is on-purpose built using HTTP protocol and follows HTTP standards as much as possible. To make sure the API will be stable and can support customers for years to come.

In general, if the resulting status code is in the range of 400-599, then we are dealing with errors.

```
GET https://api.screenshotone.com/?[options]

Content-Type: application/json

{
    "is_successful":false,
    "error_code": "an_error_code",
    "error_message": "An error message"
}
```

## Errors caused by API consumers

All errors caused by invalid requests, absent credentials, or any reasons caused by you, an API consumer, are marked with status codes 400-499. It means, that until you find a way to fix them, the request won't be executed successfully.

## API internal errors

Errors with status codes in the range 500-599 are caused by the API internal reasons and you have almost little influence over that.

But you can safely retry them.
Except in a few cases. When you get a network error (`network_error`), it might be because the site blocks the API, and there is no sense in retrying the request. Or if the site returned an error (`host_returned_error`) and it is an error within the range 400-499, it means that the API is either blocked, or you need to change the request to the site.

You still might want to try to retry errors like `network_error` and `host_returned_error` (if the host's error is `403` in the `returned_status_code` property of the response), but try to add a residential rotating proxy to that API request. Maybe the second time you can succeed and the request will work for you.

An example of the code that retries the request with a residential rotating proxy:

```javascript
const response = await fetch(
    "https://api.screenshotone.com/take?url=https://example.com&access_key=..."
);
if (!response.ok) {
    const error = await response.json();
    if (
        // add more error codes
        error.error_code === "network_error" ||
        (error.error_code === "host_returned_error" && error.returned_status_code == 403)
    ) {
        const proxy = "http://...";
        const proxyResponse = await fetch(
            `https://api.screenshotone.com/take?url=https://example.com&access_key=...&proxy=${proxy}`
        );
        if (!proxyResponse.ok) {
            const proxyError = await proxyResponse.json();
            // you can try to retry again
        }

        // the retry was sucessful
        const screenshot = await proxyResponse.blob();
    }
}
```

## Showing errors to your end users

In general, you can try to just return the error message provided by the API, but if you want to show a more user-friendly message, you can use the following code:

```javascript 
const response = await fetch("https://api.screenshotone.com/...");

// after retries and other processing, once you decide to show an error to your end user
if (!response.ok) {
    const errorData = await response.json();

    const errorMessage = generateUserFriendlyErrorMessage(errorData);

    // show the error to your end user in your UI, CLI or any other way
    showErrorToUser(errorMessage);
}

function generateUserFriendlyErrorMessage(error) {
    // these are error messages for your public users, not for you
    switch (error.error_code) {
        case "screenshots_limit_reached":
            return "The screenshot rendering is not available. Please, retry later.";
        case "concurrency_limit_reached":
        case "temporary_unavailable":
            return "Please try again in a moment.";
        case "request_not_valid":
            return "Please, make sure your request is valid and try again.";
        case "selector_not_found":
            return "The target element was not found on the page";
        case "name_not_resolved":
            return "Unable to resolve the domain name. Check that there is no typo in the URL. If this is a new site, please wait for DNS propagation.";
        case "network_error":
            return "Unable to connect to the requested URL. The site may be blocking access or temporarily down.";
        case "host_returned_error":
            if ([401, 403, 429].includes(error.returned_status_code)) {
                return "The target website blocks automated screenshot rendering.";
            }
            if (error.returned_status_code >= 500) {
                return "The target website is temporarily down. Please, retry later.";
            }
            if (error.returned_status_code == 404) {
                return "The target website returned a 404 HTTP error—the page not found.";
            }

            return `The target website returned a ${error.returned_status_code} HTTP error.`;
        case "timeout_error":
            return "The screenshot rendering timed out. Please, try again.";
        case "storage_returned_transient_error":
        case "internal_application_error":
        case "request_aborted":
            return "Failed to render the screenshot. Please try your request again";
        case "access_key_required":
        case "access_key_invalid":
        case "signature_is_required":
        case "signature_is_not_valid":
        case "invalid_storage_configuration":
        case "script_triggers_redirect":
        case "storage_access_denied":
        case "content_contains_specified_string":
        case "invalid_cookie_parameter":
        case "resulting_image_too_large":
            // these are errors that often are not caused by the end user action,
            // and they need to be fixed on your or our side
            return "The screenshot rendering failed. Please, reach out to support.";
        default:
            // return a generic error message
            // or the message provided by the API error.error_message
            return "The screenshot rendering failed. Please, reach out to support.";
    }
}
```

These are the most common errors often caused by end users. If you want to process more codes, check out [all  our errors](/docs/errors/).

## Reporting errors

All ScreenshotOne API errors are logged and we are acknowledged by them. And will react to them as fast as possible.

In general, you don't need to report to us any errors. But if it blocks your work or you want us to prioritize fixing them, please, feel free to report an error at `support@screenshotone.com`.

## Error reference

All API errors are listed in [the error reference](/docs/errors/).

# Screenshot authenticated pages

There is a few methods to screenshot authenticated pages:

1. [If the website is yours or it allows to send a custom HTTP header with the authentication token when rendering the page.](#1-custom-http-header)
2. [If the website is yours, allow to bypass authentication for ScreenshotOne servers.](#2-allow-bypassing-authentication-for-screenshotone-servers)
3. [Using cookies.](#3-using-cookies)

## 1. Custom HTTP header

If the website is yours or it allows to send a custom HTTP header with the authentication token when rendering the page, you can use the following method:

```
https://api.screenshotone.com/take?access_key=<your access key>&url=https://example.com&headers=Authorization: Bearer <your authentication token>
```

Or:

```
https://api.screenshotone.com/take?access_key=<your access key>&url=https://example.com&authorization=Bearer <your authentication token>
```

Support the header name is different, e.g. `X-API-Key`, you can use the following syntax:

```
https://api.screenshotone.com/take?access_key=<your access key>&url=https://example.com&headers=X-API-Key: <your authentication token>
```

## 2. Allow bypassing authentication for ScreenshotOne servers

This method is complicated and requires for you to configure your firewall to [allow the ScreenshotOne servers](/docs/ip-ranges/) to access the website.

## 3. Using Cookies

If the website you are trying to screenshot uses cookies to authenticate users and doesn't block automation or it is yours, you can use cookies with the ScreenshotOne API to render pages behind authentication.

I will use [ScreenshotOne's Dashboard](https://dash.screenshotone.com/) as an example. Suppose, I want screenshot the dashboard page (`https://dash.screenshotone.com/dashboard`): 

![ScreenshotOne's Dashboard](./dashboard.png)

If I screenshot it straight away like: 

```
https://api.screenshotone.com/take?access_key=<your access key>&url=https://dash.screenshotone.com/dashboard
```

I will get the following result:

![Unauthenticated](./unauthenticated.jpeg)

It is an authenticated form.

Let's check cookies for the page, after I logged in:

![Cookies](./cookies.png)

Make sure to copy all the cookie parameters, including the `domain`, `path` and other parameters: 

```
__Secure-better-auth.session_token=ZFmIsN7BVPU0Fzzd9aJ7lZU4TLSvu2L2.buMSGkHDIxhT%2B7YIl6tS82eGGLAAeRzk7FMp1YiTtK8%3D
domain=dash.screenshotone.com
path=/
HttpOnly
Secure
Lax
```

Then format it as required by the ScreenshotOne API:

```
__Secure-better-auth.session_token=ZFmIsN7BVPU0Fzzd9aJ7lZU4TLSvu2L2.buMSGkHDIxhT%2B7YIl6tS82eGGLAAeRzk7FMp1YiTtK8%3D; domain=dash.screenshotone.com; path=/; HttpOnly; Secure; Lax
```

And then try to screenshot the page again but with the cookies now:

```
https://api.screenshotone.com/take?access_key=<your access key>&url=https://dash.screenshotone.com/dashboard&cookies=__Secure-better-auth.session_token=ZFmIsN7BVPU0Fzzd9aJ7lZU4TLSvu2L2.buMSGkHDIxhT%2B7YIl6tS82eGGLAAeRzk7FMp1YiTtK8%3D; domain=dash.screenshotone.com; path=/; HttpOnly; Secure; Lax
```

The result will be as expected: 

![Authenticated](./authenticated.jpeg)

One pitfall is that likely you will need to write your own code to sign in to the website and get the cookies.

## Support

If you need help with screenshotting authenticated pages and any of the above methods does not work for you, please, contact us at `support@screenshotone.com`.

# Customize websites before screenshotting

ScreenshotOne supports a few options that can help you add any customizations to any website before rendering screenshots of it.

## Hide any element by CSS selectors

If you just need to quickly hide a few elements on the website, just use [the hide_selectors](https://screenshotone.com/docs/options/#hide_selectors) option and specify as many CSS selectors as you wish.

For example, let's hide the main header on the example.com website with:

```
https://api.screenshotone.com/take?url=https://example.com&hide_selectors=h1&access_key=<your API key>
```

Before hiding:

![A customized version of the example.com website](with_header.png)

After hiding:

![A customized version of the example.com website](without_header.png)

You can specify as many selectors as you wish, e.g.:

```
https://api.screenshotone.com/take?url=https://example.com&hide_selectors[]=h1&hide_selectors[]=p&access_key=<your API key>
```

## Add custom CSS styles

But often you want to do more than just hide a few elements. Maybe you want to change some colors of the elements, or font size, or whatever. Then you can simply add custom CSS styles with [the styles option](https://screenshotone.com/docs/options/#styles).

Don't forget to encode the code. And often, you must add a `!important` attribute to every property you use.

Let's try it with the example.com website:

```
https://api.screenshotone.com/take?url=https://example.com&styles=h1%20%7Bcolor%3A%20red%20%21important%3B%7D&access_key=<your API key>
```

Notice, that the styles parameter is URL-encoded. Let's look at the result:

![A customized version of the example.com website](example_com_with_styles.webp)

## Execute custom JavaScript code

But what if hiding elements and adding styles is not enough? We got you covered! You can any custom JavaScript code you want.

You can check out a more complex example of using scripting for integrating [Google Translate API when screenshotting websites](/docs/guides/how-to-translate-and-render-a-website-as-a-screenshot/).

:::caution
If your script causes navigation and makes the page reload, make sure to specify [the scripts_wait_until option](/docs/options/#scripts_wait_until) if you want to wait or large enough [delay](/docs/options/#delay).
:::

Let's execute an extreme example and just override the page content with:

```javascript
scripts = document.body.innerHTML = "Hello, world!";
```

The URL would look like:

```
https://api.screenshotone.com/take?scripts=document.body.innerHTML="Hello,%20world!"&url=https://example.com/&access_key=<your access key>
```

And the result is:

![A customized version of the example.com website](hello_world_example.webp)

## Click

If you use scripting to only click on some element by selector, there is a popular shortcut for that [the click option](/docs/options/#click).

```
https://api.screenshotone.com/take?click=.a-some-button-class-selector&url=https://example.com&access_key=<your access key>
```

Just specify any selector of any element and it will be clicked.

# Full-page screenshots

By default, the only thing you need to do is to set the `full_page` parameter to `true`:

```
https://api.screenshotone.com/take?url=https://example.com&full_page=true&access_key=...
```

The API tuned to balance performance and quality for the full-page screenshots. However, if you need to improve the quality of rendering, for the full-page screenshots, there is a few things you can do:

1. [Try different rendering algorithms.](#different-rendering-algorithms)
2. [Tune scrolling of the page.](#tune-scrolling)
3. [Reduce animations.](#reduce-animations)
4. [Wait more.](#wait-more)

However, improving the quality of rendering might lead to a performance degradation.

## Different rendering algorithms

By default, the API uses the `full_page` uses a simple algorithm to screenshot the full page—it asks the browser to render it and usually that means that the browser just stretches the viewport to render the full-page screenshot. It rarely but leads to rendering issues.

You can try to use a different algorithm instead—by_sections:

```
full_page_algorithm=by_sections
```

It might be better in most cases. Since it will try to scroll the page and render it section by section, and then stitch all the sections into one image.

But while scrolling the page, not every element might triggered due the speed of the scrolling and the delay between the scrolls. Try to tune scrolling.

## Tune scrolling

Try to decrease or increase the size of the scroll step:  

```
full_page_scroll_by=500
```

And increase the delay between the scrolls, it might help to render the page correctly

```
full_page_scroll_delay=1500
```

It might help to render the page better and trigger more lazy-loaded elements.

## Reduce animations

Request websites to reduce the number of animations by adding the `reduced_motion` parameter: 

```
reduced_motion=true
```

## Wait more

Add from 5 to 10 seconds to wait for the page to load:

```
delay=5
```

## Block ads, trackers, banners and other elements

Request the API to block ads, trackers, banners and other elements by use the following parameters: 

```
block_ads=true&block_trackers=true&block_cookie_banners=true&block_chats=true&block_banners_by_heuristics=true
```

## Summary 

Combining all the tips above, you might try to get the best results with something like that: 

```
https://api.screenshotone.com/take?access_key=...&url=https://example.com&full_page=true&full_page_algorithm=by_sections&full_page_scroll_by=500&full_page_scroll_delay=1500&reduced_motion=true&delay=5&block_ads=true&block_trackers=true&block_cookie_banners=true&block_chats=true&block_banners_by_heuristics=true
```

## Support 

Rendering full-page screenshots reliably is a real challenge. And even after a lot of tuning, it might not work for all the pages.

If you have any questions or suggestions, please contact us at [support@screenshotone.com](mailto:support@screenshotone.com).

# How to render website screenshots with Make

import { YouTube } from 'astro-embed';

Make (formerly Integromat) is a powerful visual platform for creating automated workflows (often called “scenarios” or “blueprints”) between different apps and services—without needing to write code. 

It helps to save time, reduce manual work, and connect various tools in an organized, automated way.

And with ScreenshotOne you can integrate website screenshot rendering into your Make workflows.

There is no official integration for Make yet, but there is a lot of ways you can use ScreenshotOne to render website screenshots in your Make workflows.

## Community Integrations 

There are integrations that are not officially made by ScreenshotOne, but you can use any of [the community-supported integrations](https://www.make.com/en/integrations/screenshotone-community).

## Tutorials 

### How to Automate ScreenshotOne with Make by Synergetic

A tutorial by [Synergetic](https://www.go-synergetic.com/apps/screenshotone) on how to automate ScreenshotOne with Make: 

<YouTube id="lzKhO9VRzgM" />

### How to generate Scrolling Screenshots ScreenshotOne with Make by Synergetic

In his guide on [how to multiply your leads tenfold using text-to-video AI automation](https://www.youtube.com/watch?v=Fild563M2Qo), Jack Roberts uses ScreenshotOne 
to generate scrolling screenshots:

<YouTube id="Fild563M2Qo" params="start=1474"  />

The same method can be applied to regular and full-page screenshots as well.

## Support 

If you have any questions, don't hesitate to reach out to our support at [support@screenshotone.com](mailto:support@screenshotone.com).

# How to automate website screenshots with n8n

[n8n](https://n8n.io/) is a free and open-source workflow platform.

It allows create workflows using a lot of different integrations with simple and intuitive drag-and-drop interface:

[![n8n UI](./n8n.webp)](https://n8n.io/)

## Community nodes

There is an official [ScreenshotOne node](https://www.npmjs.com/package/n8n-nodes-screenshotone) available for n8n.

[![ScreenshotOne node](./n8n-integration.png)](https://www.npmjs.com/package/n8n-nodes-screenshotone)

You can also find it in the [n8n community nodes](https://docs.n8n.io/integrations/community-nodes/) section.

## Guides

Guides on how to automate website screenshots with n8n:

1. [Capture URL Screenshots Automatically from Google Sheets & Drive with ScreenshotOne & Gmail Alerts](https://n8n.io/workflows/3321-capture-url-screenshots-from-google-sheets-with-screenshotone-and-save-to-drive-with-gmail-alerts/).

[![Capture URL Screenshots Automatically from Google Sheets & Drive with ScreenshotOne & Gmail Alerts](./guide.png)](https://n8n.io/workflows/3321-capture-url-screenshots-from-google-sheets-with-screenshotone-and-save-to-drive-with-gmail-alerts/)

# How to render Google Documents as JPEG, PNG or WebP screenshots

import Video from "@/components/Video.astro";

By default, you can not render Google Docs as screenshots with the ScreenshotOne API. But if you managed to export it as HTML, you can make it work.

## Make Google Documents available as HTML

To make Google Documents available as HTML, you need to export it as HTML from the Google Docs editor.

I created [a simple Google Documents example](https://docs.google.com/document/d/1cY0QhA2GGCdhsoFCJYBCeCproSMzWwvUqkbnylwUGog/edit?usp=sharing) to demonstrate how to do that. 

(1) For document, go to share settings: 

![The Google Docs share settings](./google-docs-share-settings.png)

(2) Change the settings to make the document public and shareable:

![The Google Docs share settings](./google-docs-share-settings-make-public.png)

After that you can use either Google Docs API or make the link shareable and public to everyone and then modify it to the link like:
`https://docs.google.com/document/d/<document id>/export/html`.

## Render Google Documents as screenshots

Get your ScreenshotOne API key at the [ScreenshotOne dashboard](https://dashboard.screenshotone.com/).

And then implement the following example in TypeScript or any other language you want:

```typescript
// validate URL
const documentUrl = new URL(url);
if (!documentUrl.hostname.includes("docs.google.com")) {
    throw new Error("Invalid URL: Must be a Google Doc document URL");
}

// Extract document ID from the Google Doc URL
const match = documentUrl.pathname.match(/document\/d\/([\w-]+)/);
if (!match) {
    throw new Error("Invalid Google Docs URL format");
}

const documentId = match[1];
// for documents, change to "document"
const exportUrl = `https://docs.google.com/document/d/${documentId}/export/html`;
url = exportUrl;

// Prepare ScreenshotOne API parameters
const params: Record<string, string> = {
    url: url,
    access_key: SCREENSHOTONE_ACCESS_KEY as string,    
};

const apiUrl = `https://api.screenshotone.com/take`;
console.log("Making request to ScreenshotOne API...");

// Make request to ScreenshotOne API
const screenshotResponse = await axios({
    method: "post",
    url: apiUrl,
    data: params,
    headers: {
        "Content-Type": "application/json",
    },
    responseType: "stream",
    maxContentLength: Infinity,
    maxBodyLength: Infinity,
    timeout: 60000, // increase timeout to 60 seconds
});

// Process the image
```

Notice that we use a POST HTTP request to the `https://api.screenshotone.com/take` endpoint. It is good if you want to send HTML yourself, but also works with URLs. Also, you can just send a regular GET request.

The resulting video will be something like: 

## Set custom styles

In case, you do not like how Google Slides or Documents look like by default, you can set custom styles via the `style` option:

```
style=<your CSS styles>
```
Adding such a style option to Google Documents, will make look them differently. 

## A working example

You can find a fully working example (written in Node.js/TypeScript) in the [ScreenshoOne integration examples directory](https://github.com/screenshotone/examples/tree/main/nodejs/google-slides-scrolling-screenshots). However, it is for Google Slides
and downloads HTML to render it with ScreenshotOne, but today you do not need that, you can render Google Documents and Slides directly with ScreenshotOne.

## Suggestions

1. If possible, use the official Google Docs API to get the HTML. It is more reliable and easier to use. 
2. If you build this solution for third-party use, consider if you can automate the processing of authentication with Google Docs and extract the HTML. 

## Google Slides

Check out [our guide on how to render Google Slides as scrolling screenshots](/docs/guides/google-slides-as-scrolling-screenshots/).

## Support 

In case you have any questions or suggestions, feel free to reach out at `support@screenshotone.com`.

# How to use proxies

ScreenshotOne doesn't include rotating residential proxies as part of the product, but you can plug in easily any external proxy provider you like, in three simple steps.

:::tip[Did you know?]
If you need to use proxies to bypass CAPTCHAs, [check out our guide on how to bypass CAPTCHAs](/docs/guides/how-to-bypass-captchas).
:::

## 1. Sign up to a proxy provider

There are plenty of them, like [Smartproxy](https://smartproxy.com/), [Bright Data](https://brightdata.com/), or [Geonode](https://geonode.com/).

You can find the Internet proxy providers that you prefer by price and quality. Choose and sign up for the proxy provider.

Not because it is the best one or the cheapest one, but in this guide, I will use [Smartproxy](https://smartproxy.com/) as an example.

## 2. Get the proxy URL

Choose pay-as-you-go residential proxies in Smartproxy or any other proxy provider you picked in the previous step.

And your goal is to copy the HTTP URL of the proxy with the desired configuration.

In the case of Smartproxy, it would look like:

![An example of picking the HTTP proxy endpoint in Smartproxy](smartproxy.jpg).

## 3. Use the proxy with the ScreenshotOne API

Once you have the HTTP proxy URL, not HTTPS, nor SOCKS5. You can specify it when sending an API request with the [proxy](/docs/options/#proxy) parameter, just like this:

```
https://api.screenshotone.com/take?proxy=<your proxy url>&access_key=<your API key>&url=<the site you want to screenshot>
```

Where `<your proxy url>` is your proxy URL, or in the case of our example is `http://user12345:somepass@us.smartproxy.com:10000`.

## Recommendations

A few tips to improve your success rate when using proxies:

1. **Don't use random proxies.** Use proxies located in the United States or your specific location, rather than random locations. For most proxy providers, stability is unlikely when using random locations.

2. **Don't send many requests through the same proxy.** If you plan to send many requests in parallel through the same proxy, consider using different ports if available or even different proxies. Using a single channel is highly likely to slow down your API requests, cause timeouts, and result in more errors.

3. If you encounter network issues, check the balance and reach out the proxy provider support, but we also noticed that for some providers, you sometimes need to recreate your proxy user/account to make it work again.

## Reach out if anything

You see, it was that easy. In case if you have any questions or encounter any problems, please, don't hesitate to reach out at `support@screenshotone.com`.

# Upload to S3

You can use [ScreenshotOne screenshot API](https://screenshotone.com/) to take website screenshots and upload them directly to Amazon S3 and any other S3-compatible storage like [Cloudflare R2](https://www.cloudflare.com/products/r2/), [Backblaze](https://www.backblaze.com/), and others.

I will guide through a few simple steps of how you can do it.

Today's UI for Amazon AWS console or ScreenshotOne might be a bit different, and things can change after a while, but you should sense the overall approach from the post you need to apply to make it work.

If you are familiar with AWS, you can go straight away to [configure access to S3 in ScreenshotOne](#configure-access-to-s3-in-screenshotone).

## Prepare the bucket and credentials

Open the [S3 console](https://console.aws.amazon.com/s3/) and click on the "Create bucket" button:

![Create bucket](create_bucket_button.png)

Type the bucket name, choose a region, and other important for you settings:

![A bucket form](create_bucket_form.png)

Now, let's create access keys to upload to the S3 bucket.

:::danger
Never, ever, don't share the access key to your main account with ScreenshotOne or another service. Create an IAM user with as narrow access as possible and share its keys.
:::

> [AWS Identity and Access Management (IAM) user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) is an entity that you create in AWS to represent the person or application that uses it to interact with AWS. A user in AWS consists of a name and credentials.

Before creating a user, we will create a narrow policy to restrict access to the bucket we created and only for putting objects into it.

> You manage access in AWS by creating [policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and attaching them to IAM identities (users, groups of users, or roles) or AWS resources. A policy is an object in AWS that, when associated with an identity or resource, defines their permissions. AWS evaluates these policies when an IAM principal (user or role) makes a request. Permissions in the policies determine whether the request is allowed or denied.

Open [the IAM management console](https://console.aws.amazon.com/iam/), navigate to "Policies", then click on the "Create policy" button. And one the following screen, select `S3` as a service, then allow only `PutObject` operation for the bucket with the name `screenshotone`:

![Create policy](policy_s3_put_object.png)

After clicking on the "Create policy" button and entering the policy name:

![Create policy](policy_s3_review_policy.png)

I gave a clear name to the policy as an example. You can provide whatever you like.

Then open [the IAM management console](https://console.aws.amazon.com/iam/) again and navigate to users. Once you are here, click on the "Add users" button:

![Add users](iam_console.png)

After that, type username and select "Access key - Programmatic access":

![Username and credentials](username_and_access.png)

We need to select and attach the policy we created earlier to the user:

![Select policy](select_policy.png)

The user is primarily ready, so we can skip the following steps and get to the end, where we can see credentials:

![Credentials](user_is_created.png)

Copy the credentials and store them in safe place like password manager. We will need them in the next step to configure ScreenshotOne to upload screenshots.

I will save the credentials for our example to use in the next section:

```
Access key ID: AKIAURGNZP6VM5HASWIF
Secret access key: wVd8OgAnGIEdlQaWxDwzVcOQNO03G1dgFiDyHLPT
```

## Configure access to S3 in ScreenshotOne

:::caution
If you haven't created the bucket in the `us-east-1` AWS region, please, specify your bucket region through an endpoint in a format like `https://s3.<your-region>.amazonaws.com`.
:::

You can set credentials ([Access Key ID](https://screenshotone.com/docs/options/#storage_access_key_id) and [Secret Access Key](https://screenshotone.com/docs/options/#storage_secret_access_key)) when sending an API request or you cat to go to the [access page](https://dash.screenshotone.com/access). And put all the credentials you got from Amazon AWS for S3 into the "S3 access" configuration form:

![Access page](access_page.png)

I specified the default bucket, but you can use many buckets to upload screenshots and then override the target bucket with [the storage_bucket option](https://screenshotone.com/docs/options/#storage_bucket) when using API. But for example, I use only one bucket—it is enough.

## Take a website screenshot through API with `storing` options

ScreenshotOne API has [a bunch of options related to uploading screenshots to S3 storage](https://screenshotone.com/docs/options/#storing):

-   [store](https://screenshotone.com/docs/options/#store) triggers upload of the taken screenshot, rendered HTML or PDF to the configured S3 bucket.
-   [storage_path](https://screenshotone.com/docs/options/#storage_path)—specifies the key for the file, but not an extension. The extension will be added automatically based on the specified [format](https://screenshotone.com/docs/options/#format).
-   [storage_bucket](https://screenshotone.com/docs/options/#storage_bucket)—overrides the default bucket configured in the [access page](https://dash.screenshotone.com/access).
-   [storage_class](https://screenshotone.com/docs/options/#storage_class)—allows to specify [the object storage class](https://aws.amazon.com/s3/storage-classes/).

Let's take a screenshot and upload it to S3:

```
https://api.screenshotone.com/take?access_key=0MpjJxw8Vk7ZAw&url=https://nextjs.org&store=true&storage_path=nextjs.org
```

The result is:

![Next.js](nextjs.org.jpg)

And let's check S3:

![S3 results](s3_nextjs.png)

In case you don't need to return the resulting image and speed up uploading, add `response_type=empty` to the request:

```
https://api.screenshotone.com/take?access_key=0MpjJxw8Vk7ZAw&url=https://example.com&store=true&storage_path=example.com&response_type=empty
```

The result is a white screen—zero bytes sent from the ScrenshotOne API in response. And let's again check that the screenshot is uploaded:

![S3 results](s3_all.png)

That's it. But if you want to do it asynchronously?

## Async and Webhooks

ScreenshotOne supports [asynchronous screenshot rendering and webhooks](/docs/async-and-webhooks/). You can upload your screenshots to S3 asynchronously without waiting and then receive the resulting upload URL to your server.

To do that, specify additional parameters `async`, `webhook_url`, `storage_return_location`. And only JSON response type is supported.

So the full request might look like:

```
https://api.screenshotone.com/take?access_key=0MpjJxw8Vk7ZAw&url=https://example.com&store=true&storage_path=example.com&response_type=json&async=true&webhook_url=https://example.com&storage_return_location=true
```

Read more about [asynchronous screenshot rendering and webhooks](/docs/async-and-webhooks/).

## Why upload to S3

I don't know your use case and would be happy to know it, but there are a few reasons why customers of ScreenshotOne upload website screenshots to S3.

One is to use CDN that pulls images from S3 storage, and the other is to archive screenshots, process them later, or even compare them.

## Instead of summary

It makes me happy to help people solve their problems. And even happier when people pay for that. I hope today I solved yours. Have a good day or even night, and be happy 👌

# Rendering performance

> "You are never done working on performance."
>
> Guillermo Rauch

ScreenshotOne's API is optimized for performance on permanent basis. However, due to a huge set of parameters that can be used to customize the rendering, there are some use cases where the default performance is not optimal.

The goal of this guide is to help you to tune the rendering parameters for your specific use case.

Of course, if you have any questions or need more help or assistance in performance tuning, please, reach out at `support@screenshotone.com`.

## Disable blocking ads and banners

Blocking ads, banners and other content seriously affects the performance of rendering since the API starts to listen for all the requests, waiting for elements to be shown, and many more tricks and heuristics are used to hide this type of content from the rendering.

In case if you render pages that do not contain any ads, banners or the pages belong to you and you can hide that content for the API, make sure to disable blocking ads, banners, and other content:

```
block_ads=false
block_cookie_banners=false
block_banners_by_heuristics=false
block_chats=false
```

Set these parameters explicitly to `false`, otherwise you rely on the default values that are not optimal for your use case and might be even changed in the future.

## Disable or enable tracking scripts

There is a lot of analytics and tracking scripts that might downgrade the performance of rendering. You can disable them by:

```
block_tracking=true
```

**However!** If you know that the websites you render doesn't have tracking scripts, you can disable them by:

```
block_tracking=true
```

If you do not need them, disable blocking tracking scripts:

```
block_tracking=false
```

Because, to block tracking scripts, the API needs to sniff all the requests, analyze them and block.

This is a parameter that you need to play with for use case, and see what works the best.

## Image format and quality

Use either `JPEG` or `WebP` format for images:

```
format=jpeg or format=webp
```

It is faster to generate, the size is usually smaller than other formats, so it is also faster to transfer these.

The limitation of the `WebP` format is that you can't use it for the huge full page screenshots. In general, it is not recommended to use it for the full page screenshots,
or if you do you use it make sure to set `full_page_max_height` and check that the rendering is not broken for your use case.

In many cases, especially if you generate just tiny previews of the websites, you also don't need high quality images. Try to set lower image quality for the images:

```
image_quality=80
```

And see if it satisfies your needs. However, for some formats reducing the quality might degrade performance. It is better to play with it.

## Viewport size and device scale factor

For huge viewport size, screenshot rendering will take more time. But one of the critical parameters is the `device_scale_factor`.

When you set its value to more than `1`, you double the size of the screenshot. If you are screenshots are not planned to be used for the high DPI displays, you can set it to `1` to reduce the size of the screenshot and rendering time.

```
device_scale_factor=1
```

Make sure to check that the quality fits your needs.

It is also changed automatically to higher values if you use the `viewport_device` parameter with a device that automatically increases it:

```
viewport_device=iphone_16
```

`device_scale_factor` will be set to 3. Try to set it explicitly to `1` and see if it works for your use case:

```
viewport_device=iphone_16
device_scale_factor=1
```

## Wait options

Try to play with the `wait_until` option. Start with `load` and see if it works for your case. Set it explicitly:

```
wait_until=load
```

If you anyway plan to render to full page screenshots and use scrolling, you don't need to wait for everything to loaded since
the page anyway will be scrolled to the bottom and likely this will cover and load all the content.

## Full page screenshots

### Try different algorithms

There are two algorithms for the full page screenshots: `by_sections` and `default`.

The default algorithm is the best one for the most of the cases. Try to use it first with disabled `full_page_scroll` and see if it works for your use case.

```
full_page_algorithm=default
```

However, if you need to try to use the `by_sections` algorithm:

```
full_page_algorithm=by_sections
```

It will render the page by sections, and will scroll anyway. It might be better algorithm if you need to trigger lazy loaded.

### Disable full page scrolling

If you do not need full page scrolling, disable it by:

```
full_page_scroll=false
```

It will dramatically reduce the rendering time. However, if your page contains lazy loaded content, it won't be loaded.

### Tune full page scrolling

If you anyway need to scroll pages, try to play with the settings of the scrolling algorithm:

```
full_page_scroll_delay=100
```

If that still allows to render most of the images for your use case, go for it.

## Summary

It is hard to make the API product to satisfies all the use cases and still be performant. But with some tuning, it is achievable.

Please, feel free to reach out at `support@screenshotone.com` if you have any questions or need more help or assistance in performance tuning.