PagePixels Screenshot API

Capture and analyze screenshots of websites and custom HTML with the PagePixels Screenshot API. You can schedule screenshots, take geolocation-specific screenshots, automate visual testing with AI, and extract HTML content with ease. Perfect for real-time website monitoring, SERP testing, automated data extraction, captioning, and more.

Available Packages

NPM (node/js), PIP (Python), and RubyGem (Ruby) packages are available to quickly integrate PagePixels Screenshot API with your application.

Node Package Manager 

Package:

https://www.npmjs.com/package/screenshots-pagepixels

Repository:

https://github.com/PagePixels/screenshots-pagepixels-npm
Python Package Index (PyPI) 

Package:

https://pypi.org/project/screenshots-pagepixels

Repository:

https://github.com/PagePixels/screenshots-pagepixels-python
RubyGems 

Package:

https://rubygems.org/gems/screenshots_pagepixels

Repository:

https://github.com/PagePixels/screenshots-pagepixels-ruby

Introduction

The PagePixels Screenshot API offers a comprehensive set of tools to capture and automate website screenshots, schedule snapshots, and analyze visuals across real-world locations. Key capabilities include:

Instantly capture screenshots with the Quick Snap endpoint.

Each successful request to this endpoint provides an immediate image of the specified website.

Automate scheduled captures with the Scheduled Screenshots endpoints.

Successful responses include an embed_url key for instant access to updated images.

Capture region-specific screenshots to see how your content appears across various geolocations.

Leverage AI to analyze captured images for text extraction, visual testing, and automated captioning.

Use custom HTML snapshots to capture visuals for email previews, reports, and more.

The PagePixels Screenshot API supports extensive configuration options through the Screenshot API Options, allowing you to tailor each request for precise results.

Base URL

All requests made to the PagePixels Screenshot API have the same base_url as seen below:

BASE URL 
https://api.pagepixels.com

Quick Snaps

Create an instant screenshot using the snap endpoint with only two required arguments:

Option Expected Value
url Your image's url.
access_token Your account's Private API Key.

All screenshots are highly configurable using the Screenshot API Options as parameters in your URL or POST body.

This example uses the Mars Rover Perseverance's Wikipedia page as the value for the url:

request example 


$


https://api.pagepixels.com/snap?url=https://en.wikipedia.org/wiki/Perseverance_(rover)&access_token=your-api-key

Returns the requested screenshot image as the result if successful.

JSON & HTML Parameters

There's more you can do on the snap endpoint, including:

Key Description
json Pass json=true to receive links to the image and thumbnail, instead of the raw image.
html_only Pass html_only=true to retrieve the full HTML from the web page, instead of creating a screenshot of the web page. Note, when html_only=true is set, the selector option is ignored. The website's full HTML will be returned.

Snap Custom HTML

Create screenshots from HTML content using the snap_html endpoint. This endpoint accepts HTML content directly and generates a screenshot, respecting other screenshot options.

Option Expected Value
html_content HTML content for the screenshot.
access_token Your account's Private API Key.

The snap_html endpoint respects all standard screenshot options and the json=true flag. However, the html_only=true flag is not applicable here since the HTML is provided directly.

Here's an example using HTML content:

request example 


$


https://api.pagepixels.com/snap_html?html_content=<h1>Hello World</h1>&access_token=your-api-key

Returns a screenshot of the provided HTML content if successful.

JSON Parameter

The snap_html endpoint also supports:

Key Description
json Pass json=true to receive links to the image and thumbnail, instead of the raw image.

TTL Parameter

Captured screenshots are automatically saved to Your Account. If the same URL is used again within 24 hours, the saved version is delivered via our CDN network for fast delivery.

Screenshot count

Saved deliveries do not count against your monthly screenshot limit.

The 24 hour time period can be increased or decreased by specifying the period in seconds using the ttl parameter.

For instance, the example below will capture the screenshot and then only deliver the saved version for the next 10 minutes on subsequent requests. If the URL is requested again after 10 minutes, a new screenshot will be captured and delivered.

request example 


https://api.pagepixels.com/snap?ttl=600&url=https://en.wikipedia.org/wiki/Perseverance_(rover)&access_token=your-api-key

Public Web Pages

If you use the snap endpoint on a public web page, as opposed to a backend process, you probably do not want to use your private API Key. If you do, anyone could use it without your permission.

PagePixels provides the API Secret Token and API Publishable Key to solve this problem.

API Secret Token

Use the API Secret Token to create a HMAC SHA1 hash of the URL location you would like to screenshot and use the result as the hash_key parameter.

api secret token

API Publishable Key

Use the API Publishable Key as your access_token parameter.

api publishable key

Here is a quick example of how this can work in Ruby

Ruby 
require 'openssl'

# SPECIFY THE IMAGE LOCATION

url_to_image = "https://en.wikipedia.org/wiki/Perseverance_(rover)"

# SET YOUR API SECRET TOKEN AND API PUBLISHABLE KEY

api_secret_token = "your-api-secret-token"

api_publishable_key = "your-api-publishable-key"

# GENERATE YOUR HMAC SHA1 HASH WITH YOUR SECRET TOKEN AND IMAGE URL

api_hash_key = OpenSSL::HMAC.hexdigest('sha1', api_secret_token, url_to_image)

=> "2310b69bb6ca5e2d1891c6fbe93f83844a0087fa"

# CREATE YOUR API URL WITH YOUR IMAGE URL, HASH KEY, AND API PUBLISHABLE KEY

request_location = "https://api.pagepixels.com/snap?url=#{url_to_image}&hash_key=#{api_hash_key}&access_token=#{api_publishable_key}"

=> "https://api.pagepixels.com/snap?url=https://en.wikipedia.org/wiki/Perseverance_(rover)&hash_key=2310b69bb6ca5e2d1891c6fbe93f83844a0087fa&access_token=your-api-publishable-key"

Multi-Step Screenshots

With the PagePixels Multi-Step screenshot functionality you can complete forms, navigate to different pages, click links and buttons, and login to your favorite websites prior to taking your screenshot.

To use the Multi-Step functionality, simply pass an array of actions using the multi_step_actions key.

Actions are completed in the order they are provided in the array.

Available Actions

Action Example
Click 
{"type": "click", "selector": "#your-selector"}
Hover 
{"type": "hover", "selector": "#your-selector"}
Change Notification
Learn More 		{"type": "change", "selector": "#your-selector", "send_to": "webhook", url: "https://example.com/webhook-url"}
Goto URL 
{"type": "redirect", "value": "https://example.com"}
Run Javascript 
{"type": "javascript", "value": "console.log('my javascript');"}
Evaluate Javascript 
{"type": "evaluateJs", "value": "console.log('my javascript');"}
Insert CSS 
{"type": "css", "value": "#selector{ color: red }"}
Text Field Input 
{"type": "text_field", "selector": "#the-text-field", "value": "your-value"}
Dropdown Field Selection 
{"type": "select", "selector": "#the-dropdown-field", "value": "selected value"}
Checkbox Field Input 
{"type": "checkbox", "selector": "#the-checkbox-field", "value":true}
Press Enter (to submit hidden forms) 
{"type": "submit"}
Wait X milliseconds 
{"type": "wait", "value": "5000"}
Wait For Selector 
{"type": "wait_for_selector", "selector": "#your-selector"}

Below is an example of the Multi-Step functionality using the Create Endpoint.

This example goes to https://wikipedia.org, fills in the search field with 'Perseverance Rover', and clicks the submit button before taking a screenshot.

POST
/screenshot_configs 


$


curl -X POST "https://api.pagepixels.com/screenshot_configs" \
  -d url="https://wikipedia.org/" \
  -d multi_step_actions='[{"type": "text_field", "selector": "#searchInput", "value": "perseverance rover"}, {"type": "click", "selector": "#search-form button"}]' \
  -d access_token="your-api-key"
json response 
{
  "success": true,
  "screenshot_configuration_id":"screenshot_configuration_id",
  "embed_url":"https://pagepixels.com/app/screenshots/:screenshot_configuration_id/embed",
  "job_id": "job_id"
}

Change Notifications

Keep track of changes all across the web. For example, change notifications can alert you to when a competitor's prices have changed, or when new team members are added to their 'about us' page.

Notifications can be sent to any URL location as a POST request in JSON format. For example, you can process change notifications through Zapier and populate your favorite dashboards and backend systems with the latest information.

Below is an example screenshot with a change notification configured using the Create Endpoint.

This example goes to the Ingenuity Helicopter's wikipedia page every 10 minutes and sends a Change Notification to a webhook URL every time a change is detected on the total number of flights the helicopter has taken.

POST
/screenshot_configs 


$


curl -X POST "https://api.pagepixels.com/screenshot_configs" \
  -d url="https://en.wikipedia.org/wiki/Ingenuity_(helicopter)" \
  -d scheduled_screenshot=true \
  -d scheduled_every=10 \
  -d scheduled_interval="minutes" \
  -d multi_step_actions='[{"type": "change", "selector": "#mw-content-text > div.mw-parser-output > table.infobox > tbody > tr:nth-child(24) > td", "send_to": "webhook", "url": "https://example.com/webhook"}]' \
  -d access_token="your-api-key"
json response 
{
  "success": true,
  "screenshot_configuration_id":"screenshot_configuration_id",
  "embed_url":"https://pagepixels.com/app/screenshots/:screenshot_configuration_id/embed",
  "job_id": "job_id"
}

Note: Once your screenshot has been running for awhile, you may want to see a list of all changes previously detected. You can do this using the List Change Notifications endpoint.

List Change Notifications

This endpoint provides an array of all Change Notifications for a specific screenshot configuration.

By default, the API will return 1000 records per request.

Paging Parameters

Key Description
page

The page you would like to retrieve. Default: 1.

limit

The total number of records you would like to retrieve. Minimum: 1, Maximum: 1000, Default: 1000

after

A unix timestamp (with or without milliseconds). Only records created after this time will be returned in the request. Default: none

before

A unix timestamp (with or without milliseconds). Only records created before this time will be returned in the request. Default: none

order

Can be either 'ASC' or 'DESC'. Default: 'DESC'.

Records returned in DESC (descending) order will return the most recent records first to the oldest records. Records returned in ASC (ascending) order will return the oldest records first to the newest records.

Here is a quick example of this functionality.

GET
/screenshot_configs
:screenshot_config_id
change_notifications 


$


https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id/change_notifications?access_token=your-api-key&page=1
json response 
{
  "success": true,
  "change_notifications": [
    {
      "id": "da4b9237bacccdf19c0760cab7aec4a8359010b0",
      "screenshot_configuration_id": "827b7f5d-da55-44aa-a2d5-236b75cb1a14",
      "previous_value": "18",
      "retrieved_value": "19",
      "config": {
        "type": "change",
        "selector": "#some-selector",
        "send_to": "webhook",
        "url": "http://example.com/webhook"
      },
      "sent_at": "1632624177263"
    },
    {
      "id": "356a192b7913b04c54574d18c28d46e6395428ab",
      "screenshot_configuration_id": "827b7f5d-da55-44aa-a2d5-236b75cb1a14",
      "previous_value": "17",
      "retrieved_value": "18",
      "config": {
        "type": "change",
        "selector": "#some-selector",
        "send_to": "webhook",
        "url": "http://example.com/webhook"
      },
      "sent_at": "1632624048330"
    }
  ]
}

List All Change Notifications

This endpoint provides an array of all Change Notifications found on your account, for all screenshot configurations.

By default, the API will return 1000 records per request.

Paging Parameters

Key Description
page

The page you would like to retrieve. Default: 1.

limit

The total number of records you would like to retrieve. Minimum: 1, Maximum: 1000, Default: 1000

after

A unix timestamp (with or without milliseconds). Only records created after this time will be returned in the request. Default: none

before

A unix timestamp (with or without milliseconds). Only records created before this time will be returned in the request. Default: none

order

Can be either 'ASC' or 'DESC'. Default: 'DESC'.

Records returned in DESC (descending) order will return the most recent records first to the oldest records. Records returned in ASC (ascending) order will return the oldest records first to the newest records.

Here is a quick example of this functionality.

GET
/screenshot_configs
/change_notifications 


$


https://api.pagepixels.com/change_notifications?access_token=your-api-key&page=1
json response 
{
  "success": true,
  "change_notifications": [
    {
      "id": "da4b9237bacccdf19c0760cab7aec4a8359010b0",
      "screenshot_configuration_id": "e2ac54a0-5332-451a-a63e-4ccdb3e3db32",
      "previous_value": "18",
      "retrieved_value": "19",
      "config": {
        "type": "change",
        "selector": "#some-selector",
        "send_to": "webhook",
        "url": "http://example.com/webhook"
      },
      "sent_at": "1632624177263"
    },
    {
      "id": "356a192b7913b04c54574d18c28d46e6395428ab",
      "screenshot_configuration_id": "827b7f5d-da55-44aa-a2d5-236b75cb1a14",
      "previous_value": "17",
      "retrieved_value": "18",
      "config": {
        "type": "change",
        "selector": "#some-selector",
        "send_to": "webhook",
        "url": "http://example.com/webhook"
      },
      "sent_at": "1632624048330"
    }
  ]
}

Scheduled Screenshots

With PagePixels, you can do more than just capture a single screenshot. You can schedule screenshots on recurring intervals as well.

With a Screenshot Scheduler, PagePixels is always working in the background, keeping your screenshots up to date. Every scheduled screenshot provides a simple URL that you can use to display the latest screenshot, without worrying about the screenshot configuration, TTLs, API Keys, or Tokens.

Scheduled screenshots can be created in Your Account through the user interface or completely programatically through the Screenshot API.

Basic Scheduling Options

Option Expected Value
scheduled_screenshot true or false
scheduled_every Integer greater than 1
scheduled_interval Any of: minutes, hours, days, weeks, months, years

Scheduled Screenshot Endpoints

endpoints
POST
/screenshot_configs
POST
/screenshot_configs
/:screenshot_configuration_id
/capture
GET
/screenshot_configs
/:screenshot_configuration_id
PATCH
/screenshot_configs
/:screenshot_configuration_id
GET
/jobs
/:job_id
GET
/screenshot_configs
/:screenshot_configuration_id
/screenshots
GET
/screenshot_configs
DELETE
/screenshot_configs
/:screenshot_configuration_id

Create a scheduled screenshot 


POST
/screenshot_configs

The create endpoint creates a new screenshot configuration, which can be configured with a scheduler to take screenshots on a defined scheduled interval. All screenshots are archived in Your Account.

All screenshots are highly configurable using the Screenshot API Options as parameters in your URL or POST body.

This example creates a scheduled screenshot, taken every 10 minutes
POST
/screenshot_configs 


$


curl -X POST "https://api.pagepixels.com/screenshot_configs" \
  -d scheduled_screenshot=true \
  -d scheduled_every=10 \
  -d scheduled_interval="minutes" \
  -d url="https://en.wikipedia.org/wiki/Perseverance_(rover)" \
  -d access_token="your-api-key"
json response 
{
  "success": true,
  "screenshot_configuration_id":"screenshot_configuration_id",
  "embed_url":"https://pagepixels.com/app/screenshots/:screenshot_configuration_id/embed",
  "job_id": "job_id"
}

Let's break this response down a bit.

Every PagePixels Screenshot API endpoint will return JSON, except for the snap endpoint, which returns the requested image. In this JSON response we have the following keys:

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. You can find further details about all error codes in the API Errors section below.
screenshot_configuration_id This ID is for referencing the screenshot configuration you just created in the get and update endpoints, described in more detail below.
embed_url This URL will automatically show the most recent screenshot taken for this configuration. The URL never changes and will always display quickly over our CDN, regardless of whether a new screenshot is in the process of being captured. This is great if you want to display your images on a web page without worrying about your API keys and without slowing down your users.
job_id The Job ID can be used with the status endpoint to determine if the first screenshot of the configuration has been captured. This way, you'll know if the actual screenshot image will display in the Embed URL or if your placeholder will appear instead.

Capture the next screenshot 


POST
/screenshot_configs/:screenshot_configuration_id/capture

The capture endpoint takes the screenshot_configuration_id returned by the create endpoint above and immediately starts capturing the next screenshot, regardless of the scheduled interval. This will not interrupt the scheduled screenshots.

This is great if you want to capture a screenshot quickly without waiting for your scheduler.

POST
/screenshot_configs
/:screenshot_configuration_id
/capture 


$


curl -X POST "https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id/capture" \
  -d access_token="your-api-key"
json response 
{
  "success": true,
  "job_id": "fcdbe8a0b79965d88b903c72",
  "embed_url": "https://pagepixels.com/app/screenshots/:screenshot_configuration_id/embed"
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
job_id The Job ID can be used with the status endpoint to determine if the requested screenshot has finished capturing.
embed_url This URL will automatically show the most recent screenshot taken for this configuration. The URL never changes (you'll notice it is the same as the URL returned by the create above) and will always display quickly over our CDN, regardless of whether a new screenshot is in the process of being captured. This is great if you want to display your images on a web page without worrying about your API keys and without slowing down your users.

Get screenshot configuration 


GET
/screenshot_configs/:screenshot_configuration_id

The get endpoint returns the configuration associated with any screenshot configuration created with the create endpoint.

GET
/screenshot_configs
/:screenshot_configuration_id 


$


https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id?access_token=your-api-key
json response 
{
  "success": true,
  "config": {
    "url": "https://en.wikipedia.org/wiki/Perseverance_(rover)",
    "scheduled_screenshot": true,
    "scheduled_every": 10,
    "scheduled_interval": "minutes"
  },
  "ids": {
    "last_job_id": "852b0be3675682c725e288c1",
    "screenshot_config_id": "ecc08b07-2aa1-4bbc-982c-d20d77b27cab",
    "embed_url": "https://pagepixels.com/app/screenshots/ecc08b07-2aa1-4bbc-982c-d20d77b27cb/embed"
  },
  "created_at": "1654986507120"
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
config This will contain an object containing all of the configuration parameters used when the create was originally called, or the latest configuration parameters if the screenshot configuration had been updated with the update endpoint.

Update screenshot configuration 


PATCH
/screenshot_configs/:screenshot_configuration_id

The update endpoint allows you to add and change screenshot options in the selected screenshot configuration. For instance, you could change the scheduled interval, or even the URL you'd like to capture.

This example changes the sheduled interval to every 20 minutes, and adds a wait option of 5000.
PATCH
/screenshot_configs
/:screenshot_configuration_id 


$


curl -X PATCH "https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id" \
  -d scheduled_screenshot=true \
  -d scheduled_every=20 \
  -d wait=5000 \
  -d access_token="your-api-key"
json response 
{
  "success": true,
  "config": {
    "url": "https://en.wikipedia.org/wiki/Perseverance_(rover)",
    "wait": "5000",
    "scheduled_screenshot": true,
    "scheduled_every": 20,
    "scheduled_interval": "minutes"
  }
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
config This will contain the updated configuration parameters for the Screenshot Configuration, taking into account the latest changes and additions.

Check a screenshot's current status 


GET
/jobs/:job_id

The job status endpoint checks if the screenshot associated the job_id returned by the create and capture endpoints is complete.

GET
/jobs
/:job_id 


$


https://api.pagepixels.com/jobs/:job_id?access_token=your-api-key
json response 
{
  "success": true,
  "screenshot": {
    "direct_link": "https://cdn.pagepixels.com/:screenshot_configuration_id/a2413561f48729-1618718721393.jpg",
    "direct_thumbnail_link": "https://cdn.pagepixels.com/:screenshot_configuration_id/thumb_a2413561f48729-1618718721393.jpg",
    "taken_at_timestamp": 1618718736,
    "job_id": ":job_id"
  }
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
screenshot This will contain an object containing the direct_link to the screenshot's main CDN link, the direct_thumbnail_link to the screenshot's thumbnail CDN link, the taken_at_timestamp containing the unix timestamp for when the shot was captured, and a reference to the job_id.

Update screenshot configuration 


PATCH
/screenshot_configs/:screenshot_configuration_id

The update endpoint allows you to add and change screenshot options in the selected screenshot configuration. For instance, you could change the scheduled interval, or even the URL you'd like to capture.

This example changes the sheduled interval to every 20 minutes, and adds a wait option of 5000.
PATCH
/screenshot_configs
/:screenshot_configuration_id 


$


curl -X PATCH "https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id" \
  -d scheduled_every=20 \
  -d wait=5000 \
  -d access_token="your-api-key"
json response 
{
  "success": true,
  "config": {
    "url": "https://en.wikipedia.org/wiki/Perseverance_(rover)",
    "wait": "5000",
    "scheduled_screenshot": true,
    "scheduled_every": 20,
    "scheduled_interval": "minutes"
  }
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
config This will contain the updated configuration parameters for the Screenshot Configuration, taking into account the latest changes and additions.

Check a screenshot's current status 


GET
/jobs/:job_id

The job status endpoint checks if the screenshot associated the job_id returned by the create and capture endpoints is complete.

GET
/jobs
/:job_id 


$


https://api.pagepixels.com/jobs/:job_id?access_token=your-api-key
json response 
{
  "success": true,
  "screenshot": {
    "direct_link": "https://cdn.pagepixels.com/:screenshot_configuration_id/a2413561f48729-1618718721393.jpg",
    "direct_thumbnail_link": "https://cdn.pagepixels.com/:screenshot_configuration_id/thumb_a2413561f48729-1618718721393.jpg",
    "taken_at_timestamp": 1618718736,
    "job_id": ":job_id"
  }
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
screenshot This will contain an object containing the direct_link to the screenshot's main CDN link, the direct_thumbnail_link to the screenshot's thumbnail CDN link, the taken_at_timestamp containing the unix timestamp for when the shot was captured, and a reference to the job_id.

Get all screenshots from a configuration 


GET
/screenshot_configs/:screenshot_config_id/screenshots

The Screenshots endpoint provides an array of all screenshots previously captured by the screenshot configuration.

By default, the API will return 1000 records per request.

Paging Parameters

Key Description
page

The page you would like to retrieve. Default: 1.

limit

The total number of records you would like to retrieve. Minimum: 1, Maximum: 1000, Default: 1000

after

A unix timestamp (with or without milliseconds). Only records created after this time will be returned in the request. Default: none

before

A unix timestamp (with or without milliseconds). Only records created before this time will be returned in the request. Default: none

order

Can be either 'ASC' or 'DESC'. Default: 'DESC'.

Records returned in DESC (descending) order will return the most recent records first to the oldest records. Records returned in ASC (ascending) order will return the oldest records first to the newest records.
GET
/screenshot_configs
/:screenshot_configuration_id
/:screenshots 


$


https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id/screenshots?access_token=your-api-key&page=1
json response 
{
  "success": true,
  "screenshots": [
    {
      "direct_link": "https://cdn.pagepixels.com/623226b5-43b3-4e99-a382-cac25759859d/c26d4f2a345a61-1618719664239.jpg",
      "direct_thumbnail_link": "https://cdn.pagepixels.com/623226b5-43b3-4e99-a382-cac25759859d/thumb_c26d4f2a345a61-1618719664239.jpg",
      "taken_at_timestamp": 1618719668,
      "job_id": "e04f919c15e14af4b32d8f6a"
    },
    {
      "direct_link": "https://cdn.pagepixels.com/623226b5-43b3-4e99-a382-cac25759859d/3d024eee145238-1618719630864.jpg",
      "direct_thumbnail_link": "https://cdn.pagepixels.com/623226b5-43b3-4e99-a382-cac25759859d/thumb_3d024eee145238-1618719630864.jpg",
      "taken_at_timestamp": 1618719641,
      "job_id": "f72c2502db43f98b3aee29d8"
    }
  ]
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
screenshots An array containing the screenshot information, including the direct_link to the screenshot's main CDN link, the direct_thumbnail_link to the screenshot's thumbnail CDN link, the taken_at_timestamp containing the unix timestamp for when the shot was captured, and a reference to the job_id, for each captured screenshot in the configuration.

List all screenshot configurations 


GET
/screenshot_configs

The index endpoint provides an array of all Screenshot Configurations in your account.

By default, the API will return 1000 records per request.

Paging Parameters

Key Description
page

The page you would like to retrieve. Default: 1.

limit

The total number of records you would like to retrieve. Minimum: 1, Maximum: 1000, Default: 1000

after

A unix timestamp (with or without milliseconds). Only records created after this time will be returned in the request. Default: none

before

A unix timestamp (with or without milliseconds). Only records created before this time will be returned in the request. Default: none

order

Can be either 'ASC' or 'DESC'. Default: 'DESC'.

Records returned in DESC (descending) order will return the most recent records first to the oldest records. Records returned in ASC (ascending) order will return the oldest records first to the newest records.
GET
/screenshot_configs 


$


https://api.pagepixels.com/screenshot_configs?access_token=your-api-key&page=1
json response 
{
  "success": true,
  "screenshot_configurations": [
    {
      "config": {
        "url": "https://en.wikipedia.org/wiki/Perseverance_(rover)"
        "scheduled_screenshot": true,
        "scheduled_every": 10,
        "scheduled_interval": "minutes"
      },
      "ids": {
        "last_job_id": "96efe51c04259114f911ad6e",
        "screenshot_config_id": "a7267e20-1d36-4ea5-80ce-ae2a5340de8f",
        "embed_url": "https://pagepixels.com/app/screenshots/a7267e20-1d36-4ea5-80ce-ae2a5340de8f/embed"
      },
      "created_at": "1654986407120"
    },
    {
      "config": {
        "url": "https://en.wikipedia.org/wiki/Voyager_program",
        "hover_on_selected": true
      },
      "ids": {
        "last_job_id": "852b0be3675682c725e288c1",
        "screenshot_config_id": "ecc08b07-2aa1-4bbc-982c-d20d77b27cae",
        "embed_url": "https://pagepixels.com/app/screenshots/ecc08b07-2aa1-4bbc-982c-d20d77b27cae/embed"
      },
      "created_at": "1654986507120"
    },
    {
      "config": {
        "url": "https://en.wikipedia.org/wiki/Hubble_Space_Telescope",
        "hover_on_selected": "true"
      },
      "ids": {
        "last_job_id": "2157824ff4c4a3f671130772",
        "screenshot_config_id": "c773c99f-d0c5-4c63-ae55-e504223d7321",
        "embed_url": "https://pagepixels.com/app/screenshots/c773c99f-d0c5-4c63-ae55-e504223d7321/embed"
      },
      "created_at": "1654986607120"
    },
    {
      "config": {
        "url": "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope"
      },
      "ids": {
        "last_job_id": "4aba0d925ac0fa587eda2acd",
        "screenshot_config_id": "6ffed596-78cc-46be-9119-17b274cc6156",
        "embed_url": "https://pagepixels.com/app/screenshots/6ffed596-78cc-46be-9119-17b274cc6156/embed"
      },
      "created_at": "1654986707120"
    },
    {
      "config": {
        "url": "https://en.wikipedia.org/wiki/Ingenuity_(helicopter)"
      },
      "ids": {
        "last_job_id": "1e243cb494eee50d21290ddf",
        "screenshot_config_id": "ed944090-6058-4286-a3b8-c4870759ac0f",
        "embed_url": "https://pagepixels.com/app/screenshots/ed944090-6058-4286-a3b8-c4870759ac0f/embed"
      },
      "created_at": "1654986807120"
    }
  ]
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
screenshot_configurations This will contain an array of all Screenshot Configurations in your account, including the associated ids, including the screenshot_config_id and the last_job_id, as well as the associated configuration.

Delete the screenshot configuration and its associated screenshots. 


DELETE
/screenshot_configs/:screenshot_config_id

The destroy endpoint deletes the referenced screenshot configuration and all screenshots captured using that configuration.

DELETE
/screenshot_configs
/:screenshot_configuration_id 


$


curl -X DELETE "https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id" \
  -d access_token="your-api-key"
json response 
{
  "success": true,
  "deleted": true,
  "screenshot_configuration": {
    "url": "https://en.wikipedia.org/wiki/Perseverance_(rover)",
    "wait": "5000",
    "scheduled_screenshot": true,
    "scheduled_every": 20,
    "scheduled_interval": "minutes"
  }
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
deleted This will return true if the requested screenshot configuration was successfully deleted.
screenshot_configuration This will contain the configuration of the just deleted screenshot configuration.

List all screenshots in the account. 


GET
/screenshots

The screenshots endpoint provides an array of all screenshots captured for the entire account.

By default, the API will return 1000 records per request.

Paging Parameters

Key Description
page

The page you would like to retrieve. Default: 1.

limit

The total number of records you would like to retrieve. Minimum: 1, Maximum: 1000, Default: 1000

after

A unix timestamp (with or without milliseconds). Only records created after this time will be returned in the request. Default: none

before

A unix timestamp (with or without milliseconds). Only records created before this time will be returned in the request. Default: none

order

Can be either 'ASC' or 'DESC'. Default: 'DESC'.

Records returned in DESC (descending) order will return the most recent records first to the oldest records. Records returned in ASC (ascending) order will return the oldest records first to the newest records.
GET
/:screenshots 


$


https://api.pagepixels.com/screenshots?access_token=your-api-key&page=1
json response 
{
  "success": true,
  "screenshots": [
    {
      "screenshot_configuration_id": ""
      "direct_link": "https://cdn.pagepixels.com/db270cba-8c2c-4f27-9840-5d0a0ea9ae10/c26d4f2a345a61-1618719664239.jpg",
      "direct_thumbnail_link": "https://cdn.pagepixels.com/db270cba-8c2c-4f27-9840-5d0a0ea9ae10/thumb_c26d4f2a345a61-1618719664239.jpg",
      "taken_at_timestamp": 1618719668,
      "job_id": "e04f919c15e14af4b32d8f6a"
    },
    {
      "direct_link": "https://cdn.pagepixels.com/623226b5-43b3-4e99-a382-cac25759859d/3d024eee145238-1618719630864.jpg",
      "direct_thumbnail_link": "https://cdn.pagepixels.com/623226b5-43b3-4e99-a382-cac25759859d/thumb_3d024eee145238-1618719630864.jpg",
      "taken_at_timestamp": 1618719641,
      "job_id": "f72c2502db43f98b3aee29d8"
    }
  ]
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. All error codes are described in more detail below.
screenshots An array containing the screenshot information, including the direct_link to the screenshot's main CDN link, the direct_thumbnail_link to the screenshot's thumbnail CDN link, the taken_at_timestamp containing the unix timestamp for when the shot was captured, and a reference to the job_id, for each captured screenshot in the configuration.

AI Image Analysis and Regression Testing

The PagePixels Image AI Analysis feature allows you to integrate AI-based image analysis directly into your workflow. You can submit up to 5 image URLs and 5 AI Prompts.

Prompts can analyze any image in the array or compare multiple images (e.g., “Compare the second and third images"). Prompts can also extract specific details like product prices, or simply describe the content of an image.

Note: AI Analysis is built-in to the Create Endpoint and Snap Endpoint. You do not need to use this endpoint to analyze screenshots. This dedicated endpoint allows you to analyze your own images without using the screenshot functionality.

Upgradeable Feature: Free and paid plans include 25 AI Image Analysis requests per month. Paid users can purchase additional requests at $9.99 per 1,000 requests.

Each image and each prompt sent for analysis counts as an individual "AI Image Analysis Request" for your PagePixels account.

AI Analysis Request Body Schema

Key Expected Value Description
urls Array of strings Array of image URLs to be analyzed. Each image URL can be a direct link to a PNG, JPEG (.jpeg or .jpg), WEBP, or GIF image file that's no larger than 20MB.
prompts Array of strings Corresponding array of AI prompts, one per image. Each prompt can be up to 2000 characters in length.

AI Image Analysis Endpoint 


POST
/ai/analyze

Use the post ai/analyze endpoint to submit an array of images and an array of prompts to go along with those images for an AI to analyze.

Example

Note: The example below analyzes 2 images and 3 prompts as part of the POST request, requiring a total of 5 "AI Image Analysis Requests" to run successfully.

POST
/ai/analyze 


$


curl -X POST "https://api.pagepixels.com/ai/analyze?access_token=your-api-key" \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://cdn.pagepixels.com/109b51b1-2a83-4387-8564-16669d596e96/2dc9032dff24c2-1726276315215.jpg",
    "https://cdn.pagepixels.com/26af69db-9581-4894-b00e-e075fc07b9e0/65964e2c886281-1726440056891.jpg"
  ],
  "prompts": [
    "What is the second image of?",
    "What is the first image of?",
    "Compare and contrast the two images."
  ]
}'
json response 
{
  "urls": [
    "https://cdn.pagepixels.com/109b51b1-2a83-4387-8564-16669d596e96/2dc9032dff24c2-1726276315215.jpg",
    "https://cdn.pagepixels.com/26af69db-9581-4894-b00e-e075fc07b9e0/65964e2c886281-1726440056891.jpg"
  ],
  "prompts": [
    "What is the second image of?",
    "What is the first image of?",
    "Compare and contrast the two images."
  ],
  "responses": [
    "The second image promotes the features of...",
    "The first image is about the pricing plans...",
    "Comparison:\n - Both images focus on..."
  ]
}

Response Breakdown

Key Description
urls Array of the original URLs submitted for analysis.
prompts Array of prompts corresponding to the submitted URLs.
responses Array of AI-generated responses corresponding to each prompt.

Real Location Screenshots

Create a screenshot from a specific geographical location using the snap endpoint with the real_location parameter.

This ensures that the requested screenshot is taken from a server located within the geographical region of your choice.

Learn more about geolocation screenshots and check out the geolocation screenshot web tutorial.

Option Expected Value
url The URL of the webpage for which you want a screenshot.
access_token Your account's Private API Key.
real_location The location from which to take the screenshot. Must be one of the values returned by the real_locations endpoint.

This Real Location example uses the Mars Rover Perseverance's Wikipedia page with the real_location set to "USA":

request example 


$


https://api.pagepixels.com/snap?url=https://en.wikipedia.org/wiki/Perseverance_(rover)&real_location=USA&access_token=your-api-key

In this example, the real_location is set to "USA", so the screenshot will be taken from a randomly selected city within the United States. You can replace "USA" with any valid location returned by the real_locations endpoint.

Upgradeable Feature: Free and paid plans receive 32MB of free Real Location bandwidth each month. Paid accounts can purchase additional bandwidth at $20.00/month per 2GB of bandwidth.

List All Real Locations 


GET
/real_locations

Use the get real_locations endpoint to return an array of locations you can pass to the real_location parameter. Returned locations are sorted alphabetically in ascending order.

Example

GET
/real_locations 


$


https://api.pagepixels.com/real_locations?access_token=your-api-key
json response 
{
  "success": true,
  "results": ["Afghanistan", "Alabama", "Alaska", "Albania", "All", "Andorra", "Angola", "Argentina", "Arizona", "Arkansas", "Armenia", "Aruba", "Australia", "Austria", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Belarus", "Belgium", "Belize", "Benin", "Berlin", "Bhutan", "Bolivia", "Bosnia and Herzegovina", "Brazil", "British Virgin Islands", "Bulgaria", "California", "Cambodia", "Cameroon", "Canada", "Chad", "Chicago", "Chile", "China", "Colombia", "Colorado", "Connecticut", "Costa Rica", "Côte d'Ivoire", "Croatia", "Cuba", "Cyprus", "Czech Republic", "Delaware", "Denmark", "Djibouti", "Dominica", "Ecuador", "Egypt", "Estonia", "Ethiopia", "Europe", "Europe", "Fiji", "Finland", "Florida", "France", "Gambia", "Georgia", "Georgia (US)", "Germany", "Germany", "Ghana", "Great Britain", "Greece", "Haiti", "Hawaii", "Honduras", "Hong Kong", "Houston", "Hungary", "Iceland", "Idaho", "Illinois", "India", "Indiana", "Indonesia", "Iowa", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica", "Japan", "Jordan", "Kansas", "Kazakhstan", "Kentucky", "Kenya", "Latvia", "Lebanon", "Liberia", "Liechtenstein", "Lithuania", "London", "Los Angeles", "Louisiana", "Luxembourg", "Macedonia", "Madagascar", "Maine", "Malaysia", "Maldives", "Mali", "Malta", "Maryland", "Massachusetts", "Mauritania", "Mauritius", "Mexico", "Miami", "Michigan", "Minnesota", "Mississippi", "Missouri", "Moldova", "Monaco", "Mongolia", "Montana", "Montenegro", "Morocco", "Moscow", "Mozambique", "Myanmar", "Nebraska", "Netherlands", "Netherlands", "Nevada", "New Hampshire", "New Jersey", "New Mexico", "New York", "New York", "New Zealand", "Nigeria", "North Carolina", "North Dakota", "Norway", "Ohio", "Oklahoma", "Oman", "Oregon", "Pakistan", "Panama", "Paraguay", "Pennsylvania", "Peru", "Philippines", "Poland", "Portugal", "Puerto Rico", "Qatar", "Random", "Rhode Island", "Romania", "Romania", "Russia", "Saudi Arabia", "Senegal", "Serbia", "Seychelles", "Singapore", "Slovakia", "Slovenia", "South Africa", "South Carolina", "South Dakota", "South Korea", "South Sudan", "Spain", "Sudan", "Sweden", "Switzerland", "Syria", "Taiwan", "Tennessee", "Texas", "Thailand", "Togo", "Trinidad and Tobago", "Tunisia", "Turkey", "Turkmenistan", "UAE", "Uganda", "Ukraine", "United Kingdom", "Uruguay", "US", "USA", "Utah", "Uzbekistan", "Vermont", "Vietnam", "Virginia", "Washington", "West Virginia", "Wisconsin", "Wyoming", "Yemen", "Zambia", "Zimbabwe"]
}

Response Breakdown

Key Description
success A boolean indicating whether the request was successful.
results An array of locations sorted alphabetically in ascending order.

Get Account Limits 


GET
/account_limits

Use the get account_limits endpoint to retrieve your account's current usage and limits for screenshots and real location bandwidth.

Option Expected Value
access_token Your account's Private API Key.

The following is an example of a request to retrieve account limits:

request example 


$


https://api.pagepixels.com/account_limits?access_token=your-api-key
json response 
{
  "success": true,
  "results": {
    "screenshot_limit": 10000,
    "screenshot_current_month_usage": 420,
    "real_location_bandwidth_limit_in_bytes": 33554432,
    "real_location_bandwidth_current_month_usage_in_bytes": 12345678
  }
}

Response Breakdown

Key Description
success A boolean indicating whether the request was successful.
screenshot_limit The maximum number of screenshots allowed per month for the account.
screenshot_current_month_usage The number of screenshots used so far during the current month.
real_location_bandwidth_limit_in_bytes The bandwidth limit (in bytes) for real location usage during the current month.
real_location_bandwidth_current_month_usage_in_bytes The bandwidth (in bytes) used so far during the current month for real location screenshots.

Screenshot API Options

Screenshots are highly configurable to suit nearly any need.

In addition to the standard options below, you can also use the multi_step_actions option described in more detail here.

Basic Setup
Field Type Default Description
url Text None

The URL you would like to capture. For example:

https://wikipedia.com
time_zone Text null

Emulate how a web page behaves and displays content in a set time zone. The value for the time_zone field must be a supported ICU programmatic timezone ID (e.g. "US/Eastern", "Europe/Berlin", "Asia/Tokyo", "America/Sao_Paulo", "Pacific/Auckland"). You can find the latest full list of timezone IDs in this Unicode txt document, or for a quicker reference, see this Wikipedia article.
selectors Text None

By default we take a screenshot of the entire window. However, if you provide a CSS selector here, we will take a screenshot of that page element only. Learn more about CSS selectors here:

Learn More
hover_on_selected Boolean (true or false) false

If you provided a CSS selector above, you can check this option to have us hover over the object before taking the screenshot. This gives you the ability to display the :hover styles for the associated element if needed.

Real Locations
Field Type Default Description
real_location Text false

See details and an example in this section.

Set the real_location parameter to a supported city, country, or US state to take screenshots from that geographical location through a proxy network.

Waiting
Field Type Default Description
wait Number 1500

How many milliseconds after the webpage has loaded should we wait to capture the screenshot? Maximum wait time is 20 seconds (20000 milliseconds). This is useful if the webpage you are capturing takes awhile to load.
wait_for Text None

Provide a CSS selector that should appear on the page before the screenshot is captured. For example:

#id-to-wait-for
Page Setup
Field Type Default Description
fullpage Boolean (true or false) false

By default, screenshots capture only the image within the viewport. With Full Page selected, the entire page is scrolled and captured.
page_width Number 1920

This is the width of the viewport when the screenshot is taken. Default is 1920 pixels. This can be used to emulate different device dimensions.
page_height Number 1000

This is the height of the viewport when the screenshot is taken. Default is 1000 pixels. This can be used to emulate different device dimensions.
Image Settings
Field Type Default Description
image_format Text jpeg Generate screenshots in jpeg, png, or webp image formats.
placeholder_url Text https://cdn.pagepixels.com/placeholder.png

The image at the provided URL will be displayed until the first screenshot is captured. The provided URL should return an image.
quality Number 100

Quality defines the JPEG compression, where 1 produces the lowest quality image and 100 creates the highest quality image. The higher the quality, the larger the image will be. This setting is ignored if you are producing a PNG or WebP image.
scale_factor Text 1 Scale factor 2 produces a Retina display scaled image.
CSS Injection
Field Type Default Description
css_inject Text None Inject any CSS declarations you need into the page.
Javascript Injection
Field Type Default Description
js_inject Text None Inject any Javascript you need on the page.
AI Analysis
Field Type Default Description
analyze_image_with_ai Boolean (true or false) false Set this field to true to enable image analysis using AI powered by OpenAI's ChatGPT. When enabled, the AI will process the image and provide insights based on the provided ai_prompt.
ai_prompt Text None A text prompt that guides the AI in analyzing the image. This prompt should specify what information you want the AI to extract or explain. Examples include:

  • "Extract the business's current rating from this page."
  • "Analyze the branding elements present in the image."
  • "Identify the target audience based on the marketing material."
  • "Summarize the key marketing message conveyed in the image."
Custom Headers
Field Type Default Description
headers Text None
Custom Cookies
Field Type Default Description
cookies Text None
Language, Location, and User Agent
Field Type Default Description
accept_language Text None

Instruct the browser to ask the website to display a specific language. This is great for websites that support multiple languages. You can learn more about this setting here:

Learn More

user_agent Text None

Give the browser additional information about the type of device that is connecting to the website. You can learn more about the User Agent setting here:

Learn More
latitude Text None

Provide location information to the browser. You can learn more about the latitude, longitude, and accuracy configuration settings here:

Learn More
longitude Text None

Provide location information to the browser. You can learn more about the latitude, longitude, and accuracy configuration settings here:

Learn More
accuracy Number None

Provide location information to the browser. You can learn more about the latitude, longitude, and accuracy configuration settings here:

Learn More
Ads, Tracking, and Javascript
Field Type Default Description
no_ads Boolean (true or false) false
no_tracking Boolean (true or false) false
no_cookie_banners Boolean (true or false) false
disable_js Boolean (true or false) false
disable_third_party_js Boolean (true or false) false

Discards Javascript resources from outside of the requested domain. This can help speed up load times, improve performance, and reduce the risk of a timeout.
Screenshot Configuration Information
Field Type Default Description
custom_title Text None

Add a custom title to your screenshot configuration

custom_description Text None

Add a custom description to your screenshot configuration.

API Errors

If success is false in the response, then you will also receive an error_code to provide additional information.

Here is a quick list of the errors you may encounter using the API.

API Error Codes
missing_access_token Code returned when no API key is provided.
invalid_access_token Code returned when the API key is not associated with a valid account.
missing_or_invalid_url Code returned when the URL provided is required and missing or is invalid.
invalid_hash_key Code returned when the HMAC SHA1 hash is invalid when using the API Secret Token and API Publishable Key for public web page usage.
usage_limit_exceeded Code returned when your Monthly Screenshot Allotment is depleted for the current month.
rate_limit_exceeded We typically limit API requests to 1000 per minute, with some leeway for bursts.
screenshot_configuration_not_found Code returned when the provided screenshot_configuration_id does not match a valid screenshot in your account.
screenshot_already_in_progress Code returned by the capture endpoint if a screenshot is already currently in progress for the requested Screenshot Configuration.
screenshot_capturing_in_progress Code returned by the status endpoint if the selected job_id is currently in progress.
screenshot_not_found Code returned by the status endpoint if the selected job_id is not found under your account.
invalid_schedule_provided Code returned if the schedule provided in the create or update endpoints is invalid in some way. The JSON will also include a note key, which will provide more information on what happened.
invalid_multi_step_actions Code returned if the multi_step_actions array is not valid. Click here to learn more about the Multi-Step Functionality
billing_not_up_to_date Code returned if the account is missing a payment and is not on the free plan.
invalid_page_number Code returned when an invalid page number is received. Page numbers should an integer greater than 0.
invalid_limit Code returned when an invalid limit is received. The record limit should be an integer greater than 0 and less than 1001.
invalid_after_date Code returned when an invalid after date is received. The after date should be a unix timestamp with or without milliseconds.
invalid_before_date Code returned when an invalid before date is received. The before date should be a unix timestamp with or without milliseconds.
unexpected_error We encountered an issue on our end and have been notified. Please contact support if you continue to experience the issue.

And here is a short summary of HTTP status codes for easy reference.

HTTP Status Codes
200 - OK Success
400 - Bad Request Request contains bad syntax or can't be fulfilled.
401 - Unauthorized Request does not contain a valid API key.
403 - Forbidden The API key was valid but doesn't have the necessary permissions to perform the request.
404 - Not Found The requested resource doesn't exist.
405 - Method Not Allowed The requested resource does not support the method / verb used in the request.
408 - Request Timeout The request took longer than the allotted wait time.
429 - Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 - Server Errors The server failed to fulfil the request. Wait a few minutes and try the request again. If the errors persist, please contact us.