> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenshotmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Screencast

> Capture high-quality animated screenshots of webpages.

It’s simple to use: you only need to submit your `access_key` and a url `url` of a webpage. The API will return the animated screenshot of the webpage.

## Getting started

### REST

The Screencast API, like all of ScreenshotMAX’s APIs, is organized around REST. It is designed to use predictable, resource-oriented URL’s and to use HTTP status codes to indicate errors.

### HTTPS

The Screencast API requires all communications to be secured TLS 1.2 or greater.

### API Versions

All of ScreenshotMAX’s APIs are versioned. The Screencast API is currently on Version 1.

### Your Access Key

Your access key is your unique authentication key to be used to access ScreenshotMAX APIs.
To authenticate your requests, you will need to append your access key to the base URL as a query parameter for GET requests.
You can also use the `X-Access-Key` header to pass your access key.
You can find your access key in your [account dashboard](https://app.screenshotmax.com/access).

### Base URL

```
https://api.screenshotmax.com/v1/screencast
```

### Validation endpoint

ScreenshotMAX’s Screencast API simply requires your unique access key and url to be passed in the URL. The API will return an animated screenshot of the webpage.

```
https://api.screenshotmax.co/v1/screencast
?access_key=YOUR_ACCESS_KEY
&url=https://example.com
```

This was a successful request, so the API returned a 200 OK response. The animated screenshot is returned in the body of the response.

### Request parameters

<ParamField query="access_key" type="string" required>
  Your unique access key. You can find your access key in your [account dashboard](https://app.screenshotmax.com/access).
</ParamField>

<ParamField query="url" type="string" required initialValue="https://example.com">
  The URL of the webpage you want to rendering of. Must be a valid URL and accessible from the internet.
  If the URL contains a querystring, it must be URL-encoded.

  For example, `https://example.com/test?param=1` should be passed as `https%3A%2F%2Fexample.com%2Ftest%3Fparam%3D1`.
</ParamField>

<ParamField query="format" type="string" default="mp4">
  The format of the animated screenshot. Available formats are `webm`, `mp4`, `mov`, `avi`.
</ParamField>

<ParamField query="duration" type="number" default="5">
  The duration of the animated screenshot in seconds. The default value is `5` seconds. Maximum value is `30` seconds.
</ParamField>

<ParamField query="scenario" type="string" default="video">
  The scenario of the animated screenshot. Available scenarios are `video`, and `scroll`.
  The `video` scenario captures the entire webpage as a video. The `scroll` scenario captures the webpage by scrolling down.
</ParamField>

<ParamField query="scroll_by_amount" type="number" default="1000">
  The `scroll_by_amount` parameter is only applicable for the `scroll` scenario. It specifies the amount to scroll in pixels for one step. The default value is `1000` pixels.
</ParamField>

<ParamField query="scroll_by_delay" type="number" default="500">
  The `scroll_by_delay` parameter is only applicable for the `scroll` scenario. It specifies the delay between each scroll in milliseconds. The default value is `500` milliseconds.
</ParamField>

<ParamField query="scroll_by_duration" type="number" default="1500">
  The `scroll_by_duration` parameter is only applicable for the `scroll` scenario. It specifies the total duration for all steps of scrolls in milliseconds. The default value is `1500` milliseconds.
</ParamField>

<ParamField query="scroll_back" type="bool" default="true">
  The `scroll_back` parameter is only applicable for the `scroll` scenario. When set to `true`, the animated screenshot will scroll back to the top of the page after reaching the bottom.
</ParamField>

<ParamField query="scroll_back_delay" type="number" default="800">
  The `scroll_back_delay` parameter is only applicable for the `scroll` scenario. It specifies the delay before scrolling back to the top in milliseconds. The default value is `800` milliseconds.
</ParamField>

<ParamField query="scroll_easing" type="string" default="linear">
  The `scroll_easing` parameter is only applicable for the `scroll` scenario. It specifies the easing function to use for the scroll animation.
  Available values are `linear`, `ease_in_quad`, `ease_out_quad`, `ease_in_out_quad`, `ease_in_cubic`, `ease_out_cubic`, `ease_in_out_cubic`, `ease_in_quart`, `ease_out_quart`, `ease_in_out_quart`, `ease_in_quint`, `ease_out_quint` and `ease_in_out_quint`.
</ParamField>

<ParamField query="gpu_rendering" type="bool" default="false">
  Whether to use GPU rendering. Only available for **scale paid plan.**
</ParamField>

<ParamField query="capture_beyond_viewport" type="bool" default="false">
  Whether to capture content beyond the viewport.
</ParamField>

<ParamField query="viewport_device" type="string">
  The device type for the viewport.
</ParamField>

<ParamField query="viewport_width" type="number" default="1280">
  The width of the viewport in pixels.
</ParamField>

<ParamField query="viewport_height" type="number" default="1080">
  The height of the viewport in pixels.
</ParamField>

<ParamField query="viewport_landscape" type="bool">
  Whether the viewport should be in landscape mode.
</ParamField>

<ParamField query="viewport_has_touch" type="bool">
  Whether the viewport has touch capabilities.
</ParamField>

<ParamField query="viewport_mobile" type="bool">
  Whether the viewport is a mobile device.
</ParamField>

<ParamField query="device_scale_factor" type="number">
  The device scale factor for the viewport.
</ParamField>

<ParamField query="clip_x" type="number">
  The x-coordinate of the top-left corner of the clipping region.
</ParamField>

<ParamField query="clip_y" type="number">
  The y-coordinate of the top-left corner of the clipping region.
</ParamField>

<ParamField query="clip_width" type="number">
  The width of the clipping region.
</ParamField>

<ParamField query="clip_height" type="number">
  The height of the clipping region.
</ParamField>

<ParamField query="block_annoyance" type="string" default="cookies_banner">
  The annoyance to block. Options include `none`, `cookies_banner`, `ads`, `tracking`.
</ParamField>

<ParamField query="block_ressources" type="string">
  The resources to block. Options include `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest` and `other`.
</ParamField>

<ParamField query="media_type" type="string" default="screen">
  The media type for the rendering. Options include `screen` and `print`.
</ParamField>

<ParamField query="vision_deficiency" type="string">
  The vision deficiency for the rendering. Options include `reduced_contrast`, `blurred_vision`, `deuteranopia`, `achromatopsia`.
</ParamField>

<ParamField query="dark_mode" type="bool" default="false">
  Whether to use dark mode for the rendering.
</ParamField>

<ParamField query="reduced_motion" type="bool" default="false">
  Whether to reduce motion for the rendering.
</ParamField>

<ParamField query="geolocation_accuracy" type="number">
  The accuracy of the geolocation in meters. Minimum is `0`. Maximum is `1000`.
</ParamField>

<ParamField query="geolocation_latitude" type="number">
  The latitude of the geolocation. Minimum is `-90`. Maximum is `90`.
</ParamField>

<ParamField query="geolocation_longitude" type="number">
  The longitude of the geolocation. Minimum is `-180`. Maximum is `180`.
</ParamField>

<ParamField query="hide_selectors" type="string[]">
  The selectors to hide in the content. This allows you to remove specific elements from the rendering.
  Example: `hide_selectors=div.header,div.footer`.
</ParamField>

<ParamField query="click_selector" type="string">
  The selector to click in the content. This allows you to interact with specific elements before the rendering.
  Example: `click_selector=button.submit`.
</ParamField>

<ParamField query="attachment_name" type="string">
  The name of the attachment, without the extension filename. This is the name that will be used when downloading the response.
  Extension will be automatically added based on the `format` parameter.
</ParamField>

<ParamField query="timezone" type="string">
  The time zone for the request. This allows you to simulate different time zones.
  Available time zones from the [IANA Time Zone Database](https://www.iana.org/time-zones).
</ParamField>

<ParamField query="authorization" type="string">
  The authorization header to use for the request. This should be a base64-encoded string (e.g., for Basic Auth, encode "username:password" using base64). This allows you to authenticate with the webpage before capturing the content.
</ParamField>

<ParamField query="user_agent" type="string">
  The user agent to use for the request. This allows you to simulate different browsers and devices.
</ParamField>

<ParamField query="cookies" type="string[]">
  The cookies to use for the request. This allows you to simulate different sessions and states.
  Example: `cookies=name=value; name2=value2`.
</ParamField>

<ParamField query="headers" type="string[]">
  The headers to use for the request. This allows you to simulate different requests and responses.
  Example: `headers=header1:value1; header2:value2`.
</ParamField>

<ParamField query="ip_location" type="string">
  The IP location to use for the request. This allows you to simulate requests from different countries by routing them through proxy servers with corresponding IP addresses.
  This feature is only available on **scale paid plan**.

  Supported locations:

  * United States (`us`)
  * China (`cn`)
  * Europe (`eu`) (random EU country)
  * Canada (`ca`)
  * Mexico (`mx`)
  * United Kingdom (`gb`)
  * Germany (`de`)
  * France (`fr`)
  * Switzerland (`ch`)
  * India (`in`)
  * Japan (`jp`)
  * South Korea (`kr`)
  * Russia (`ru`)
  * Brazil (`br`)
  * Australia (`au`)
</ParamField>

<ParamField query="proxy" type="string">
  The proxy to use for the request. This allows you to route the request through a different IP address.
  The proxy must be in the format `http://username:password@host:port` or `https://username:password@host:port`.
</ParamField>

<ParamField query="bypass_csp" type="bool" default="false">
  Whether to bypass the Content Security Policy (CSP) of the webpage. This allows you to capture content of webpages with strict CSPs.
</ParamField>

<ParamField query="delay" type="number" default="0">
  The delay in seconds before rendering. This allows you to wait for specific elements to load before capturing the content. Maximum is `30`.
</ParamField>

<ParamField query="timeout" type="number" default="30">
  The timeout in seconds for the rendering. This allows you to set a maximum time for the request to complete. Maximum is `30`.
</ParamField>

<ParamField query="wait_until" type="string[]" default="['domcontentloaded']">
  The conditions to wait for before rendering. This allows you to ensure that specific elements are loaded before capturing the content.
  Available options include:

  * `load`: Wait for the load event to be fired.
  * `domcontentloaded`: Wait for the DOMContentLoaded event to be fired.
  * `networkidle0`: Wait for no network connections for at least 500 ms.
  * `networkidle2`: Wait for no more than 2 network connections to be active for at least 500 ms.
</ParamField>

<ParamField query="metadata_icon" type="bool" default="false">
  Whether to include the metadata icon in the response. This allows you to capture the favicon of the webpage. The link of the icon will be included in the header `X-Screenshotmax-Metadata-Icon`.
</ParamField>

<ParamField query="metadata_title" type="bool" default="false">
  Whether to include the metadata title in the response. This allows you to capture the title of the webpage. The title will be included in the header `X-Screenshotmax-Metadata-Title`.
</ParamField>

<ParamField query="metadata_fonts" type="bool" default="false">
  Whether to include the metadata fonts in the response. This allows you to capture the fonts used on the webpage. The fonts will be included in the header `X-Screenshotmax-Metadata-Fonts`.
</ParamField>

<ParamField query="metadata_hash" type="bool" default="false">
  Whether to include the metadata hash in the response. This allows you to capture the hash of the webpage. The hash will be included in the header `X-Screenshotmax-Metadata-Hash`.
</ParamField>

<ParamField query="metadata_status" type="bool" default="false">
  Whether to include the metadata status in the response. This allows you to capture the HTTP status code of the webpage. The status code will be included in the header `X-Screenshotmax-Metadata-Status`.
</ParamField>

<ParamField query="metadata_headers" type="bool" default="false">
  Whether to include the metadata headers in the response. This allows you to capture the headers of the webpage. The headers will be included in the header `X-Screenshotmax-Metadata-Headers`.
</ParamField>

<ParamField query="cache" type="bool" default="false">
  Whether to store the content of the rendering in the cache. This allows you to store the rendered content for a specified time-to-live (TTL) period.
</ParamField>

<ParamField query="cache_ttl" type="number" default="604800">
  The time-to-live (TTL) for the cache in seconds. This allows you to set a maximum time for the cached resources to be valid. Maximum is 30 days in seconds (`2592000`).
</ParamField>

<ParamField query="async" type="bool" default="false">
  Whether to use asynchronous processing for the requestt. This allows you to capture content without blocking the request.
</ParamField>

<ParamField query="webhook_url" type="string">
  The callback URL for asynchronous processing. This allows you to receive the response via a webhook.
  The webhook will be triggered when the response is ready.
  The webhook URL must be a valid URL and must be accessible from the internet.
  The webhook URL must be HTTPS and must support the `POST` method.
  More information about webhooks can be found in the [async & webhook documentation](https://docs.screenshotmax.com/start/async-webhooks).
</ParamField>

<ParamField query="webhook_signed" type="bool" default="true">
  Indicates whether the webhook request should be signed. Enabling this option allows you to verify the authenticity of incoming webhook requests.
  For more details, refer to the [async & webhook documentation](https://docs.screenshotmax.com/start/async-webhooks).
</ParamField>

<ParamField query="signature" type="string">
  The cryptographic signature used to verify the authenticity of the request.
  For more information on how to compute and validate this signature, see the [signed requests documentation](https://docs.screenshotmax.com/start/signed-request").
</ParamField>

## Response and error codes

### Error Codes

Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.

| Code | Type                  | Details                                                                                                      |
| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| 200  | OK                    | The request was successful.                                                                                  |
| 400  | Bad request           | The request was malformed or invalid.                                                                        |
| 401  | Unauthorized          | The request was rejected due to an invalid access key or missing signature when signed requests are enabled. |
| 403  | Forbidden             | The signature provided is invalid. Occurs when signed requests are enabled.                                  |
| 402  | Payment Required      | Access denied due to an unpaid invoice. **Applies to paid plans.**                                           |
| 423  | Locked                | The request was denied due to insufficient quota.                                                            |
| 429  | Too Many Requests     | The rate limit has been exceeded (too many requests per minute).                                             |
| 500  | Internal server error | The request failed due to an internal server error.                                                          |