PagePixels API

Automate screenshot creation and scheduled screenshots with the PagePixels API.

Available Packages

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


Package:

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

Repository:

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


Package:

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

Repository:

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


Package:

https://rubygems.org/gems/screenshots_pagepixels

Repository:

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

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

Authentication

Add the Private API Key to any request as the access_token argument. Check out an example using the Quick Snap endpoint.

Click here to get your Free API Key →

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.

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

Click Here to get your Free API Secret Token →

API Publishable Key

Use the API Publishable Key as your access_token parameter.

Click Here to get your Free 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');"}`
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

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

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.

Field	Type	Default	Description
url	Text	None	The URL you would like to capture. For example: https://wikipedia.com
time_zone	Text	GMT	Emulate how a web page behaves and displays content in a set timezone. Default is GMT. For our API: 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.

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

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

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.

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.

Field	Type	Default	Description
css_inject	Text	None	Inject any CSS declarations you need into the page.

Field	Type	Default	Description
js_inject	Text	None	Inject any Javascript you need on the page.

Field	Type	Default	Description
headers	Text	None

Field	Type	Default	Description
cookies	Text	None

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

Field	Type	Default
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

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.

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.

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.

PagePixels API

Screenshot count

API Secret Token

API Publishable Key

Available Actions

Basic Scheduling Options

Scheduled Screenshot Endpoints

This example creates a scheduled screenshot, taken every 10 minutes

Response Breakdown

Response Breakdown

This example changes the sheduled interval to every 20 minutes, and adds a wait option of 5000.

Response Breakdown

Response Breakdown

Response Breakdown

Response Breakdown

Response Breakdown

Response Breakdown

This example changes the sheduled interval to every 20 minutes, and adds a `wait` option of 5000.