Scheduled screenshots

Set up recurring screenshot captures that run automatically. Monitor website changes, track competitor updates, or build visual archives over time.

Create schedule

POST /v1/schedules

Request body

{
  "name": "Homepage Monitor",
  "url": "https://example.com",
  "schedule": "0 9 * * *",
  "timezone": "America/New_York",
  "options": {
    "viewport": { "width": 1920, "height": 1080 },
    "format": "png",
    "fullPage": false,
    "blockAds": true
  },
  "webhookUrl": "https://your-server.com/webhooks/scheduled",
  "webhookSecret": "your-secret",
  "retentionDays": 30,
  "startsAt": "2025-02-01T00:00:00Z",
  "endsAt": null
}

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Schedule name (max 255 chars)
`url`	string	Yes	URL to capture
`schedule`	string	Yes	Cron expression or interval
`timezone`	string	No	Timezone for cron (default: `UTC`)
`options`	object	No	Screenshot options
`webhookUrl`	string	No	Webhook for capture notifications
`webhookSecret`	string	No	Webhook signature secret
`retentionDays`	integer	No	Days to keep captures (1-365, default: 30)
`startsAt`	string	No	ISO 8601 start time
`endsAt`	string	No	ISO 8601 end time

Schedule formats

Cron expressions

Standard 5-field cron format:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Examples:

Expression	Description
`0 9 * * *`	Every day at 9:00 AM
`0 /4 * *`	Every 4 hours
`0 9 * * 1-5`	Weekdays at 9:00 AM
`0 0 1 * *`	First day of each month at midnight
`0 9,12,18 * * *`	At 9 AM, 12 PM, and 6 PM daily

Interval format

Simple intervals for common schedules:

Format	Description
`@hourly`	Every hour at minute 0
`@daily`	Every day at midnight
`@weekly`	Every Sunday at midnight
`@monthly`	First day of month at midnight

Screenshot options

Same as screenshot API:

{
  "options": {
    "viewport": { "width": 1920, "height": 1080 },
    "device": null,
    "format": "png",
    "fullPage": false,
    "quality": 80,
    "delay": 0,
    "waitFor": null,
    "waitUntil": "load",
    "timeout": 30000,
    "darkMode": false,
    "customCss": null,
    "hideSelectors": [],
    "blockAds": false,
    "blockCookieBanners": false,
    "blockLevel": "none"
  }
}

Response

{
  "scheduleId": "sched_abc123xyz",
  "name": "Homepage Monitor",
  "url": "https://example.com",
  "schedule": "0 9 * * *",
  "timezone": "America/New_York",
  "status": "active",
  "nextRunAt": "2025-01-16T14:00:00Z",
  "createdAt": "2025-01-15T10:30:00Z"
}

List schedules

GET /v1/schedules

Response

{
  "schedules": [
    {
      "scheduleId": "sched_abc123xyz",
      "name": "Homepage Monitor",
      "url": "https://example.com",
      "schedule": "0 9 * * *",
      "status": "active",
      "nextRunAt": "2025-01-16T14:00:00Z",
      "lastRunAt": "2025-01-15T14:00:00Z"
    }
  ],
  "total": 1
}

Get schedule

GET /v1/schedules/{scheduleId}

Response

Full schedule details including recent captures.

Update schedule

PATCH /v1/schedules/{scheduleId}

Request body

Only include fields you want to update:

{
  "name": "Updated Name",
  "schedule": "0 */2 * * *",
  "options": {
    "fullPage": true
  }
}

Pause/resume schedule

POST /v1/schedules/{scheduleId}/pause
POST /v1/schedules/{scheduleId}/resume

Delete schedule

DELETE /v1/schedules/{scheduleId}

Deleting a schedule also deletes all associated captures. This cannot be undone.

Get schedule captures

GET /v1/schedules/{scheduleId}/captures

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Results per page (1-100)
`offset`	integer	`0`	Pagination offset
`startDate`	string	-	Filter from date (ISO 8601)
`endDate`	string	-	Filter to date (ISO 8601)

Response

{
  "captures": [
    {
      "captureId": "cap_001",
      "capturedAt": "2025-01-15T14:00:00Z",
      "status": "completed",
      "result": {
        "url": "https://storage.allscreenshots.com/abc.png",
        "size": 245678,
        "width": 1920,
        "height": 1080
      }
    },
    {
      "captureId": "cap_002",
      "capturedAt": "2025-01-14T14:00:00Z",
      "status": "completed",
      "result": {
        "url": "https://storage.allscreenshots.com/def.png",
        "size": 234567,
        "width": 1920,
        "height": 1080
      }
    }
  ],
  "total": 30,
  "limit": 20,
  "offset": 0
}

Examples

Daily homepage monitoring

curl -X POST 'https://api.allscreenshots.com/v1/schedules' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Daily Homepage",
    "url": "https://example.com",
    "schedule": "0 9 * * *",
    "timezone": "America/New_York",
    "options": {
      "fullPage": true,
      "blockAds": true,
      "blockCookieBanners": true
    },
    "webhookUrl": "https://your-server.com/webhooks/daily-capture",
    "retentionDays": 90
  }'

Hourly competitor tracking

curl -X POST 'https://api.allscreenshots.com/v1/schedules' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Competitor Pricing",
    "url": "https://competitor.com/pricing",
    "schedule": "@hourly",
    "options": {
      "waitFor": ".pricing-table",
      "waitUntil": "networkidle"
    },
    "retentionDays": 7
  }'

Business hours only

curl -X POST 'https://api.allscreenshots.com/v1/schedules' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Dashboard Status",
    "url": "https://internal-dashboard.example.com",
    "schedule": "0 9-17 * * 1-5",
    "timezone": "Europe/London",
    "options": {
      "viewport": { "width": 1920, "height": 1080 }
    }
  }'

Schedule limits

Plan	Active schedules	Minimum interval
Free	1	Daily
Starter	5	Hourly
Pro	25	15 minutes
Enterprise	Custom	1 minute

Scheduled captures count against your monthly quota. A daily schedule uses ~30 screenshots per month.

Scheduled screenshots

On this page