Screenshot

POST

screenshot

curl --request POST \
  --url https://api.screenshotmax.com/v1/screenshot \
  --header 'Content-Type: application/json' \
  --data '{
  "access_key": "<string>",
  "url": "<string>",
  "html": "<string>",
  "format": "<string>",
  "image_quality": 123,
  "image_width": 123,
  "image_height": 123,
  "omit_background": true,
  "full_page": true,
  "full_page_scroll": true,
  "full_page_scroll_by_amount": 123,
  "full_page_scroll_by_duration": 123,
  "gpu_rendering": true,
  "capture_beyond_viewport": true,
  "viewport_device": "<string>",
  "viewport_width": 123,
  "viewport_height": 123,
  "viewport_landscape": true,
  "viewport_has_touch": true,
  "viewport_mobile": true,
  "device_scale_factor": 123,
  "clip_x": 123,
  "clip_y": 123,
  "clip_width": 123,
  "clip_height": 123,
  "block_annoyance": "<string>",
  "block_ressources": "<string>",
  "media_type": "<string>",
  "vision_deficiency": "<string>",
  "dark_mode": true,
  "reduced_motion": true,
  "geolocation_accuracy": 123,
  "geolocation_latitude": 123,
  "geolocation_longitude": 123,
  "hide_selectors": [
    "<string>"
  ],
  "click_selector": "<string>",
  "attachment_name": "<string>",
  "timezone": "<string>",
  "authorization": "<string>",
  "user_agent": "<string>",
  "cookies": [
    "<string>"
  ],
  "headers": [
    "<string>"
  ],
  "ip_location": "<string>",
  "proxy": "<string>",
  "bypass_csp": true,
  "delay": 123,
  "timeout": 123,
  "wait_until": [
    "<string>"
  ],
  "metadata_image_size": true,
  "metadata_icon": true,
  "metadata_title": true,
  "metadata_fonts": true,
  "metadata_hash": true,
  "metadata_status": true,
  "metadata_headers": true,
  "cache": true,
  "cache_ttl": 123,
  "async": true,
  "webhook_url": "<string>",
  "webhook_signed": true
}'

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 screenshot of the webpage.

Getting started

REST

The Screenshot 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 Screenshot API requires all communications to be secured TLS 1.2 or greater.

API Versions

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

Your Access Key

Your access key is your unique authentication key to be used to access ScreenshotMAX API. You have to include your access key in the request body as a JSON object. You can also use the X-Access-Key header to pass your access key. You can find your access key in your account dashboard.

Base URL

https://api.screenshotmax.com/v1/screenshot

Validation endpoint

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

POST https://api.screenshotmax.com/v1/screenshot
{
  "access_key": "YOUR_ACCESS_KEY",
  "url": "https://example.com"
}

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

Request parameters

access_key

string

required

Your unique access key. You can find your access key in your account dashboard.

url

string

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.

Either url or html must be provided.

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

html

string

This parameter allows you to provide raw HTML content to render and capture as a screenshot. It must be a valid HTML string.

Either url or html must be provided.

Example: html=<html><body><h1>Hello, World!</h1></body></html>

format

string

default:"jpeg"

The format of the screenshot. Available formats are jpeg, jpg, png, webp, gif. jpg is an alias for jpeg.

image_quality

number

default:"80"

The quality of the image. This parameter is only applicable for jpeg, jpg, webp formats. Allowed values range from 1 to 100.

image_width

number

The image_width and image_height parameters let you generate a thumbnail version of the screenshot. When specified, the screenshot is resized to fit within the given width and height while preserving the aspect ratio. The image will be as large as possible without exceeding the specified dimensions.
If only one parameter is provided, the other is automatically calculated to maintain the aspect ratio.

image_height

number

omit_background

bool

default:"false"

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.

full_page

bool

default:"false"

Whether to take a full page screenshot.

full_page_scroll

bool

default:"false"

Whether to scroll the page to take a full page screenshot. This is useful for pages that load content dynamically as you scroll.

full_page_scroll_by_amount

number

The amount of pixels to scroll per step.

full_page_scroll_by_duration

number

default:"400"

The duration in milliseconds for each step.

gpu_rendering

bool

default:"false"

Whether to use GPU rendering. Only available for scale paid plan.

capture_beyond_viewport

bool

default:"false"

Whether to capture content beyond the viewport.

viewport_device

string

The device type for the viewport.

viewport_width

number

default:"1280"

The width of the viewport in pixels.

viewport_height

number

default:"1080"

The height of the viewport in pixels.

viewport_landscape

bool

Whether the viewport should be in landscape mode.

viewport_has_touch

bool

Whether the viewport has touch capabilities.

viewport_mobile

bool

Whether the viewport is a mobile device.

device_scale_factor

number

The device scale factor for the viewport.

clip_x

number

The x-coordinate of the top-left corner of the clipping region.

clip_y

number

The y-coordinate of the top-left corner of the clipping region.

clip_width

number

The width of the clipping region.

clip_height

number

The height of the clipping region.

block_annoyance

string

default:"cookies_banner"

The annoyance to block. Options include none, cookies_banner, ads, tracking.

block_ressources

string

The resources to block. Options include document, stylesheet, image, media, font, script, texttrack, xhr, fetch, eventsource, websocket, manifest and other.

media_type

string

default:"screen"

The media type for the rendering. Options include screen and print.

vision_deficiency

string

The vision deficiency for the rendering. Options include reduced_contrast, blurred_vision, deuteranopia, achromatopsia.

dark_mode

bool

default:"false"

Whether to use dark mode for the rendering.

reduced_motion

bool

default:"false"

Whether to reduce motion for the rendering.

geolocation_accuracy

number

The accuracy of the geolocation in meters. Minimum is 0. Maximum is 1000.

geolocation_latitude

number

The latitude of the geolocation. Minimum is -90. Maximum is 90.

geolocation_longitude

number

The longitude of the geolocation. Minimum is -180. Maximum is 180.

hide_selectors

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.

click_selector

string

The selector to click in the content. This allows you to interact with specific elements before the rendering. Example: click_selector=button.submit.

attachment_name

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.

timezone

string

The time zone for the request. This allows you to simulate different time zones. Available time zones from the IANA Time Zone Database.

authorization

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.

user_agent

string

The user agent to use for the request. This allows you to simulate different browsers and devices.

string[]

The cookies to use for the request. This allows you to simulate different sessions and states. Example: cookies=name=value; name2=value2.

headers

string[]

The headers to use for the request. This allows you to simulate different requests and responses. Example: headers=header1:value1; header2:value2.

ip_location

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)

proxy

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.

bypass_csp

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.

delay

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.

timeout

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.

wait_until

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.

metadata_image_size

bool

default:"false"

Whether to include the metadata image width and height in the screenshot. This allows you to capture the dimensions of the screenshot. The dimensions will be included in the header X-Screenshotmax-Metadata-Image-Size.

metadata_icon

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.

metadata_title

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.

metadata_fonts

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.

metadata_hash

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.

metadata_status

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.

metadata_headers

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.

cache

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.

cache_ttl

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).

async

bool

default:"false"

Whether to use asynchronous processing for the requestt. This allows you to capture screenshots without blocking the request.

webhook_url

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.

webhook_signed

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.

Response and error codes

The API response is returned in binary format. The response is a screenshot of the webpage in the specified format. The response headers include the following:

Content-Type: The content type of the response. This indicates the format of the screenshot.
Content-Disposition: The content disposition of the response. This indicates how the screenshot should be handled by the browser. If the attachment_name parameter is provided, the filename will be included in this header.
X-Screenshotmax-Request-Id: The unique identifier for the request. This can be used to track the request in the logs.
X-Screenshotmax-Metadata-Icon: The URL of the icon of the webpage. This is only included if the metadata_icon parameter is set to true.
X-Screenshotmax-Metadata-Title: The title of the webpage. This is only included if the metadata_title parameter is set to true.
X-Screenshotmax-Metadata-Fonts: The fonts used on the webpage. This is only included if the metadata_fonts parameter is set to true.
X-Screenshotmax-Metadata-Hash: The hash of the screenshot. This is only included if the metadata_hash parameter is set to true.
X-Screenshotmax-Metadata-Status: The HTTP status code of the webpage. This is only included if the metadata_status parameter is set to true.
X-Screenshotmax-Metadata-Headers: The headers of the webpage. This is only included if the metadata_headers parameter is set to true.
X-Screenshotmax-Metadata-Image-Size: The dimensions of the screenshot. This is only included if the metadata_image_size parameter is set to true.

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.

Screenshot Screencast

curl --request POST \
  --url https://api.screenshotmax.com/v1/screenshot \
  --header 'Content-Type: application/json' \
  --data '{
  "access_key": "<string>",
  "url": "<string>",
  "html": "<string>",
  "format": "<string>",
  "image_quality": 123,
  "image_width": 123,
  "image_height": 123,
  "omit_background": true,
  "full_page": true,
  "full_page_scroll": true,
  "full_page_scroll_by_amount": 123,
  "full_page_scroll_by_duration": 123,
  "gpu_rendering": true,
  "capture_beyond_viewport": true,
  "viewport_device": "<string>",
  "viewport_width": 123,
  "viewport_height": 123,
  "viewport_landscape": true,
  "viewport_has_touch": true,
  "viewport_mobile": true,
  "device_scale_factor": 123,
  "clip_x": 123,
  "clip_y": 123,
  "clip_width": 123,
  "clip_height": 123,
  "block_annoyance": "<string>",
  "block_ressources": "<string>",
  "media_type": "<string>",
  "vision_deficiency": "<string>",
  "dark_mode": true,
  "reduced_motion": true,
  "geolocation_accuracy": 123,
  "geolocation_latitude": 123,
  "geolocation_longitude": 123,
  "hide_selectors": [
    "<string>"
  ],
  "click_selector": "<string>",
  "attachment_name": "<string>",
  "timezone": "<string>",
  "authorization": "<string>",
  "user_agent": "<string>",
  "cookies": [
    "<string>"
  ],
  "headers": [
    "<string>"
  ],
  "ip_location": "<string>",
  "proxy": "<string>",
  "bypass_csp": true,
  "delay": 123,
  "timeout": 123,
  "wait_until": [
    "<string>"
  ],
  "metadata_image_size": true,
  "metadata_icon": true,
  "metadata_title": true,
  "metadata_fonts": true,
  "metadata_hash": true,
  "metadata_status": true,
  "metadata_headers": true,
  "cache": true,
  "cache_ttl": 123,
  "async": true,
  "webhook_url": "<string>",
  "webhook_signed": true
}'

Animated Screenshot

Pdf

Scrape

Scheduled Tasks

Others

Screenshot

Getting started

REST

HTTPS

API Versions

Your Access Key

Base URL

Validation endpoint

Request parameters

Response and error codes

Error Codes

Screenshot

Animated Screenshot

Pdf

Scrape

Scheduled Tasks

Others

​Getting started

​REST

​HTTPS

​API Versions

​Your Access Key

​Base URL

​Validation endpoint

​Request parameters

​Response and error codes

​Error Codes

Getting started

REST

HTTPS

API Versions

Your Access Key

Base URL

Validation endpoint

Request parameters

Response and error codes

Error Codes