NPM (node/js), PIP (Python), and RubyGem (Ruby) packages are available to quickly integrate PagePixels Screenshot API with your application.
PagePixels API
Automate screenshot creation and scheduled screenshots with the PagePixels API.
Automate screenshot creation and scheduled screenshots with the PagePixels API.
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.
Add the Private API Key to any request as the access_token
argument. Check out an example using the Quick Snap endpoint.
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:
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.
|
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:
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.
|
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.
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.
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.
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.
Use the
API Publishable Key
as your
access_token
parameter.
Here is a quick example of how this can work in Ruby
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.
Action | Example |
---|---|
Click |
|
Hover |
|
Change Notification
Learn More |
{"type": "change", "selector": "#your-selector", "send_to": "webhook", url: "https://example.com/webhook-url"} |
Goto URL |
|
Run Javascript |
|
Insert CSS |
|
Text Field Input |
|
Dropdown Field Selection |
|
Checkbox Field Input |
|
Press Enter (to submit hidden forms) |
|
Wait X milliseconds |
|
Wait For 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.
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.
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.
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.
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.
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.
Option | Expected Value |
---|---|
scheduled_screenshot | true or false |
scheduled_every | Integer greater than 1 |
scheduled_interval | Any of: minutes, hours, days, weeks, months, years |
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.
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.
|
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.
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.
|
The get
endpoint returns the configuration associated with any screenshot configuration created with the create
endpoint.
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.
|
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.
wait
option of 5000.
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. |
The job status
endpoint checks if the screenshot associated the job_id returned by the create
and capture
endpoints is complete.
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.
|
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. |
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.
|
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. |
The destroy
endpoint deletes the referenced screenshot configuration and all screenshots captured using that configuration.
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. |
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. |
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.
|
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: |
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 |
---|---|---|---|
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: |
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: |
latitude | Text | None |
Provide location information to the browser. You can learn more about the latitude, longitude, and accuracy configuration settings here: |
longitude | Text | None |
Provide location information to the browser. You can learn more about the latitude, longitude, and accuracy configuration settings here: |
accuracy | Number | None |
Provide location information to the browser. You can learn more about the latitude, longitude, and accuracy configuration settings here: |
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 |
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. |
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. |