GET 25 FREE SCREENSHOTS PER MONTH  →
pagepixels
START FREE →
API REFERENCE

Scheduled Screenshots

Capture screenshots on a recurring schedule. Every configuration gets an Embed URL that always shows the latest image.

BASE URL https://api.pagepixels.com
GET YOUR FREE API KEY →

Scheduled Screenshots

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

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

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

Basic Scheduling Options

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

Scheduled Screenshot Endpoints

Create a scheduled screenshot

POST /screenshot_configs

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

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

AI analysis: Scheduled screenshots can include an AI analysis on every capture. Add analyze_image_with_ai=true with an ai_prompt, or define ai_structured_fields to get JSON back each time. Use ai_provider to run the analysis on your own AI account. See AI Analysis Screenshots.

This example creates a scheduled screenshot, taken every 10 minutes:

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

Let's break this response down a bit.

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

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. See this section for error code information.
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 REQUEST /screenshot_configs/:screenshot_configuration_id/capture bash 
curl -X POST "https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id/capture" \
  -d access_token="your-api-key"
JSON RESPONSE 
{
  "success": true,
  "job_id": "fcdbe8a0b79965d88b903c72",
  "embed_url": "https://pagepixels.com/app/screenshots/:screenshot_configuration_id/embed"
}

Response Breakdown

Key Description
success This key's value will always be a boolean (true or false) indicating whether the request was successful. If it is false, there will be an accompanying error_code describing the problem. See this section for error code information.
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 REQUEST /screenshot_configs/:screenshot_configuration_id http 
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. See this section for error code information.
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.

Required: The url field is required for the update endpoint.

AI options can be changed here as well: ai_prompt, ai_prompt_mode, ai_structured_fields, ai_provider and ai_model. The next capture uses the new settings. See AI Analysis Screenshots.

Keep it scheduled: When updating a scheduled screenshot configuration, make sure to include scheduled_screenshot=true in your request. Otherwise, if scheduled_screenshot=true is omitted, the screenshot configuration will change to a one-time (unscheduled) screenshot configuration.

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

PATCH REQUEST /screenshot_configs/:screenshot_configuration_id bash 
curl -X PATCH "https://api.pagepixels.com/screenshot_configs/:screenshot_configuration_id" \
  -d url="https://en.wikipedia.org/wiki/Perseverance_(rover)" \
  -d scheduled_screenshot=true \
  -d scheduled_every=20 \
  -d scheduled_interval="minutes" \
  -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. See this section for error code information.
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 REQUEST /jobs/:job_id http 
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. See this section for error code information.
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 REQUEST /screenshot_configs/:screenshot_configuration_id/screenshots http 
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. See this section for error code information.
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 REQUEST /screenshot_configs http 
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. See this section for error code information.
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 REQUEST /screenshot_configs/:screenshot_configuration_id bash 
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. See this section for error code information.
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.

Support

Questions? Contact us anytime by email:

Or send us a message through our Support page.

FREE PLAN

Start free. Upgrade when you’re ready.

Every feature and integration is included on the free plan. No credit card and no phone number required.

CREATE FREE ACCOUNT →
Free $0 / month
25 screenshots every month
32 MB of Real Location proxy bandwidth
25 AI Analysis credits