PagePixels API v1.0

Automate screenshot creation and scheduled screenshots with the PagePixels API.

Introduction

The PagePixels API follows RESTful conventions and is made available to programmatically:

Take an immediate screenshot using the Quick Snap endpoint.

A successful call to this endpoint returns the requested image as the result.

Configure screenshots on a schedule using the Scheduled Screenshots endpoints.

A successful call to any of these endpoints returns JSON-encoded responses and includes the embed_url key.

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

Base URL

All requests made to the PagePixels 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 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.

If preferred, you can pass the json=true option 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

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');"}
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":"http://api.pagepixels.com:3001/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":"http://api.pagepixels.com:3001/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 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_config_id/screenshots
GET /screenshot_configs
DELETE /screenshot_configs/:screenshot_config_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 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":"http://api.pagepixels.com:3001/app/screenshots/:screenshot_configuration_id/embed",
  "job_id": "job_id"
}

Let's break this response down a bit.

Every PagePixels 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": "http://api.pagepixels.com:3001/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_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_config_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_config_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.

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

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 browser when the screenshot is taken.
page_height Text 1000

This is the height of the browser when the screenshot is taken.
Image Settings
Field Type Default Description
image_format Text jpeg
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 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.
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

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.