Documentation

Introduction

The SavePage API can be used to programmatically retrieve screenshot image of any URL.

Using the powerful rendering engine of the real Chrome browser, you can quickly get a perfect snapshot of any website.

Quick start

How to get access to the SavePage API

The SavePage uses API keys for authorization. An API key is a special access token that the client needs to provide as a query parameter when making API calls.

You can sign up for a free API key here. Our Free Plan offers generous limits for getting started with SavePage.

API Endpoint

The endpoint will accept either GET or POST requests. For maximum security, always use POST HTTPS requests.

https://api.savepage.io/v1/

Required parameters

Our API uses query parameters since they are the simplest and the most common type of parameters. When using GET request they appear at the end of the request URL after a question mark (?), with name=value pairs separated by ampersands (&). When using POST request, query parameters are sent in the body with appropriate Content-Type header.

NameDescriptionExampleRequired
keyYour API key123456Yes
qURL you want to request a snapshot from*https://www.google.comYes

*Since this parameter can contain reserved characters :/?#[]@!$&'()*+,;= it should be sent as percent-encoded (encodeURIComponent/urlencode).

Example API request

https://api.savepage.io/v1/?key=123456&q=https://www.google.com

Optional parameters

NameDescriptionExampleDefaultPlans
widthPage viewport width in pixels8001440Basic/Pro
heightPage viewport height in pixels600900Basic/Pro
fullpageRequest full page rendertruefalseBasic/Pro
thumb_widthResize screenshot image based on width in pixels400-Basic/Pro
delayWait for the specified number of seconds after the webpage has loaded20Basic/Pro
nocookiePrevent cookie banners and popups from being displayedtruefalseAll
noadsPrevent ads, tracking, and analytics codetruefalseAll
formatImage format, jpeg or png are acceptedjpegjpegAll
refreshRefresh the screenshot if the cached version is older than n seconds3600-All
user_agentCustom User-Agent header*Firefox 77-All
accept_languageCustom Accept-Language headeren-US-All
maxageSpecify the time in seconds for Cache-Control response header36002629746All
cookiePass login or other information stored in the Cookie data**SID=zx5r3Vm; q=5-All
hashRequired when using API Secret word, md5(URL+APISecret)8udI3nt3xidnwq90In-All

*Since this parameter can contain reserved characters :/?#[]@!$&'()*+,;= it should be sent as percent-encoded (encodeURIComponent/urlencode).

**Limited to POST requests for security reasons. This data should be sent in the POST request body.

Example: requesting mobile website

https://api.savepage.io/v1/?key=123456&q=https://www.google.com&width=390&height=844&accept_language=fr-CA&user_agent=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%2012_2%20like%20Mac%20OS%20X%29%20AppleWebKit%2F605.1.15%20%28KHTML%2C%20like%20Gecko%29%20Mobile%2F15E148

Example: POST request using CURL

curl -X POST https://api.savepage.io/v1 --data "key=123456&q=https://www.google.com&width=300" --output image.jpg

Response

The successful API response will be sent as HTTP 200 OK, and it will contain the screenshot image.

The following headers will be sent with each response:

ValueDescription
Cache-Control: public, max-age=2629746;How long the content stays in the browser’s cache (configurable)
Last-Modified: Thu, 09 Sep 2021 07:44:07 GMTTime when the image was last modified
Content-Type: image/jpegImage type (configurable)
Content-Length: 44360Image size in bytes

If the browser issues a request with the If-Modified-Since header, and if the image hasn’t been modified since the last modified time, then a 304 - Not modified response is generated. This response tells the browser that the image in its local cache hasn’t changed, and its cache lifetime can be renewed.

Note: Other headers from intermediate proxies and CDN may be present as well.

Caching

The SavePage API will cache all requested screenshot images. The exact TTL depends on various parameters and it can take up to a month for all cached images to expire.

If the API request is sent with the refresh=-1 parameter, the screenshot will be re-rendered, the image will be updated, and the Last-Modified header will be set accordingly.

Errors

If the request cannot be successfully completed, an HTTP response with a 422 status code will be returned. The response from the API may also contain one or more error elements in the JSON response. This information can be used to determine what went wrong.

Error codes:

CodeDescription
461Cannot verify the API Key
462Invalid or blank URL sent
471Invalid security hash, access denied
472IP restricted, access denied
473Origin restricted, access denied
474Too many requests from the same IP address
481Too many workers, limit exceeded for this plan
482Too many requests, limit exceeded for this plan
483Too many screenshots, limit exceeded for this plan
490Rendering error, cannot generate screenshot
491Cache error, cannot fetch the cached image

Example error reponse:

{"error":"Cannot verify the API Key"}

Rendering Engine

Our rendering engine can only retrieve publicly accessible pages. Unfortunately, we cannot guarantee the correct screenshot response for every single URL. Some of the reasons for the failed, blank, or inaccurate screenshot are beyond our control:

  • Pages that require authentication or login
  • Slow pages or servers with slow response times
  • Advanced bot-prevention installed at the targeted website
  • Captcha or Paywall protection installed
  • Temporary networking issues or downtimes
  • Restrictions based on IP address or range of addresses (known cloud providers block)

Rate limits

Requests to the API are rate-limited based on your current subscription plan. The hourly counters will reset on a rolling basis using the sliding window algorithm.

Subscription PlanRate LimitSimultaneous Requests
Free10 unique screenshots, 100 cached requests / per hour1 dedicated worker
Basic20 unique screenshots, 200 cached requests / per hour5 dedicated workers
Pro100 unique screenshots, 1000 cached requests / per hour10 dedicated workers