Automate Monitoring Website Changes Automatically with Watch API

Watching websites for changes is a perfect use case for automation. Instead of manually checking or building brittle polling scripts, use Supacrawler's Watch API to:

Schedule automatic checks at your preferred frequency
Detect content changes with precision using targeted selectors
Receive email notifications when changes occur
Optionally capture screenshots for visual verification

Quick Start

First, install one of our SDKs (recommended):

Install SDK

npm install @supacrawler/js

Create a Watch Job

Using the Dashboard

The easiest way to create a watch job is through the dashboard:

You can configure notification preferences to receive alerts when your watch job runs or only when content changes:

Using Code

Let's monitor a pricing page daily, target the pricing table with a CSS selector, and send alerts by email when changes occur:

Create a daily watch job

import { SupacrawlerClient } from '@supacrawler/js'

const client = new SupacrawlerClient({ apiKey: process.env.SUPACRAWLER_API_KEY || 'YOUR_API_KEY' })
const created = await client.watchCreate({
  url: 'https://example.com/pricing',
  frequency: 'daily',
  notify_email: '[email protected]',
  selector: '#pricing-table',
})
console.log(`Watch ID: ${created.watch_id}`)

Monitor Results

Fetch the current status and recent check results. When screenshots are enabled, image URLs are time-limited signed URLs (expire after ~15 minutes). Download and store them if you need long-term access.

Retrieve watch details and results

import { SupacrawlerClient } from '@supacrawler/js'

const client = new SupacrawlerClient({ apiKey: process.env.SUPACRAWLER_API_KEY || 'YOUR_API_KEY' })
const watchId = 'YOUR_WATCH_ID'
const details = await client.watchGet(watchId)

console.log(`Status: ${details.watch?.status}`)
for (const result of details.results ?? []) {
  console.log(`${result.executed_at}: Changed: ${result.has_changed}, Type: ${result.change_type}`)
  if (result.image_url) {
    console.log(`Screenshot: ${result.image_url}`)
  }
}

Manage Watch Jobs

Control the lifecycle of your watch jobs with these common operations:

Manage watch jobs

import { SupacrawlerClient } from '@supacrawler/js'

const client = new SupacrawlerClient({ apiKey: process.env.SUPACRAWLER_API_KEY || 'YOUR_API_KEY' })
const watchId = 'YOUR_WATCH_ID'

// Pause monitoring temporarily
await client.watchPause(watchId)

// Resume monitoring
await client.watchResume(watchId)

// Trigger an immediate check
await client.watchCheck(watchId)

// Delete the watch job permanently
await client.watchDelete(watchId)

Advanced Configuration

Customize your watch jobs with these powerful options:

const advancedWatch = await client.watchCreate({
  url: 'https://competitor.com/pricing',
  frequency: 'custom',
  custom_frequency: '0 9 * * MON-FRI', // Weekdays at 9am
  selector: '.pricing-table',
  notify_email: '[email protected]',
  notification_preference: 'changes_only', // or 'all_runs'
  include_html: true,  // Store HTML for detailed comparison
  include_image: true, // Take screenshots
  full_page: true,     // Capture entire page
  quality: 90          // High-quality screenshots
})

Best Practices

Target what matters: Use CSS selectors to monitor specific elements and reduce noise
selector: '#pricing-table' // Only monitor the pricing table
Choose the right frequency: Start with daily or weekly checks and adjust as needed
frequency: 'daily' // Options: hourly, daily, weekly, monthly, custom
Include evidence: Enable screenshots and HTML capture for comprehensive change detection
include_image: true,
include_html: true
Handle signed URLs: Screenshot URLs expire after ~15 minutes; download them promptly if needed

With the Watch API, you get reliable change detection with minimal configuration — no cron jobs, no browser fleet, no brittle scripts.