Visualping API: How to Trigger Website Screenshots and Check for Page Changes

The Visualping API lets you create and manage website monitors and retrieve changes. To get change results pushed to another system, configure a webhook: the API configures the monitor, while the webhook delivers a JSON change event with links to screenshots and other available data. The documented create-monitor endpoint is POST https://job.api.visualping.io/v2/jobs; it creates a monitor that checks on its configured interval rather than acting as a general-purpose one-shot screenshot endpoint. See the Visualping API reference and the Visualping API setup guide.

What the API does, and when the screenshot arrives

A monitor defines the URL, capture scope, monitoring mode, frequency, sensitivity, and other settings. Visualping checks that page according to the monitor configuration. When it detects a qualifying change, a configured webhook can push a structured event to your endpoint. This is different from calling an endpoint to synchronously capture a fresh screenshot on demand.

• Create and configure: send a write-authorized request to the jobs API.
• List monitors: use the documented jobs listing endpoint and its filters.
• Receive results: configure webhook notifications in the monitor settings and consume their payloads.
• Manage and retrieve changes: the help guide describes these API capabilities; consult the current reference for the exact endpoint and request shape before implementing operations not shown here.

Visualping supports monitoring an entire page or a selected area, and visual, text, or code-oriented change detection. The reference documents crop coordinates and XPath/CSS selectors for scoping a job. Visualping’s product overview describes the monitoring modes and page scope.

1. Create an API key and authenticate

1. Open Settings → Developer in Visualping and create a key. Business users need an Admin to access Developer settings.
2. Choose the narrowest scope that works: a workspace key for one workspace, or organization scope if the integration needs multiple workspaces. Choose Write if it must create or modify monitors; Read access is for reading data.
3. Copy the key when it is shown and store it in a secret manager or environment variable. It is displayed only once. The help page documents a maximum of five keys per organization.
4. Send it on every API request as Authorization: Bearer YOUR_API_KEY. Never put the token in the URL: query strings can be logged or exposed through intermediary behavior.

API keys are the recommended authentication method in the reference. It also documents an email/password ID-token flow and refresh-token flow; use those only when needed and protect the account credentials and tokens with the same care. See key scope, access, and storage guidance and the authentication reference.

2. Create a monitor

Set VISUALPING_API_KEY in your environment before running the examples. For a Business account, the request also requires workspaceId; use the ID for the workspace your key can access. The examples use documented request fields and placeholders. They do not assume a particular response body.

cURL

curl --request POST \
  --url https://job.api.visualping.io/v2/jobs \
  --header "Authorization: Bearer $VISUALPING_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/pricing",
    "description": "Watch pricing page",
    "mode": "VISUAL",
    "active": true,
    "interval": "1440",
    "trigger": "Any Change"
  }'

Python

import os
import requests

api_key = os.environ["VISUALPING_API_KEY"]
payload = {
    "url": "https://example.com/pricing",
    "description": "Watch pricing page",
    "mode": "VISUAL",
    "active": True,
    "interval": "1440",
    "trigger": "Any Change",
}

response = requests.post(
    "https://job.api.visualping.io/v2/jobs",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.status_code)
print(response.text)

Node.js

const apiKey = process.env.VISUALPING_API_KEY;
if (!apiKey) throw new Error("Set VISUALPING_API_KEY first");

const payload = {
  url: "https://example.com/pricing",
  description: "Watch pricing page",
  mode: "VISUAL",
  active: true,
  interval: "1440",
  trigger: "Any Change",
};

const response = await fetch("https://job.api.visualping.io/v2/jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const body = await response.text();
if (!response.ok) {
  throw new Error(`Visualping returned ${response.status}: ${body}`);
}
console.log(response.status, body);

For a Business workspace, include the required workspaceId in the request body, following the current reference’s expected type and format. The API reference documents url as required and lists mode, interval, trigger, crop or selector, preactions, notification settings, and other configuration. Check that reference for the current accepted values and field details.

3. Choose what the monitor captures

Setting	What it controls	Decision
url	Page to monitor	Use the stable canonical page URL. For pages whose content depends on query parameters, include the intended parameters.
mode	Comparison type; documented values include VISUAL, WEB, TEXT, and ALL	Choose visual comparison for rendered appearance, text for wording, or a broader mode when the change signal calls for it. Confirm mode semantics in the live reference.
interval	Check frequency in minutes, represented as a string in the reference	The listed default is 1440 (daily); documented common values include 5, 15, 30, 60, 360, 720, and 1440. Availability can depend on the account; verify current account limits.
Trigger	Sensitivity for notifying about a detected change	Use a low threshold for small changes that matter; a higher threshold can reduce alerts from minor visual differences.
Crop / selector	Limits the monitored region or element	Use crop coordinates or XPath/CSS selector when unrelated page areas would create noise. Recheck selectors when the site changes its markup.
Preactions	Actions before a check, including documented click and type actions	Use only the interactions required to reveal the target state; the page may change its controls or load flow.
Active status and schedule	Whether and when the monitor runs	Set activation and any supported schedule deliberately, especially when monitoring should occur only during a particular window.
Notifications and retention	Delivery and storage behavior	Set a webhook or another supported notification method and choose retention/summary options only as needed.

The reference lists trigger categories, but the trigger guide gives the clearest threshold descriptions: Any Change, Tiny over 1%, Medium over 10%, Major over 25%, and Gigantic over 50%. These are notification thresholds, not accuracy guarantees or universal measures of semantic importance. A page can have a meaningful wording change with a small visual difference, or a large visual shift caused by an irrelevant banner. Tune the threshold against the signal you want. Visualping trigger definitions.

4. Configure a webhook to receive screenshots and changes

Webhook delivery is the documented push path to downstream systems. The Visualping help guide describes setup through the monitor’s Notifications settings:

1. Create an HTTPS endpoint or obtain a webhook URL from a receiver such as n8n, Zapier, Microsoft Power Automate, Make, Integrately, or Workato.
2. Open the monitor’s Notifications settings and select Webhook.
3. Paste the endpoint URL and use Test. Confirm the receiver gets the sample payload before relying on live change events.
4. Have your receiver parse the JSON, handle absent optional fields, and persist the event identifier/context needed by your application.

The API reference describes notification configuration as part of job settings, but the help guide’s current setup procedure is through the job UI. Do not assume a particular webhook configuration schema or endpoint unless it appears in the current API reference. Visualping explicitly lists n8n workflow automation and Webhooks by Zapier among the receiving options.

What the webhook payload contains

The documented payload includes job and workspace context where applicable, the monitored URL, description, UTC detection time, links to baseline and current screenshots, a visual preview, prior/current HTML snapshot links, change percentage, added and removed text, and dashboard links. Some fields are conditional and can be omitted entirely when not configured or relevant. Examples include labels, PDF links, AI importance, extracted data, and error details.

{
  "event": "change",
  "job_id": 123456,
  "url": "https://example.com/pricing",
  "datetime": "UTC detection time",
  "original": "URL of baseline screenshot",
  "current": "URL of current screenshot",
  "preview": "URL of visual difference preview",
  "html_previous": "URL of previous HTML snapshot",
  "html_current": "URL of current HTML snapshot",
  "change": "change percentage",
  "added_text": "text added, when available",
  "removed_text": "text removed, when available"
}

This is a schema illustration using the documented field names, not a captured event or guaranteed complete payload. Treat screenshot and snapshot values as URLs supplied by the event; do not hard-code them. Check for field presence before using optional data. The extracted_data field is a configured capability; the current guide says custom extraction requires a Solutions plan and support configuration, so do not build a workflow that assumes it is generally available.

5. Consume events reliably

• Accept quickly: validate the request and persist the event, then do slower work asynchronously in your own queue.
• Make processing repeat-safe: design downstream actions so repeated delivery or a retry does not create duplicate business effects. Use job ID, event type, timestamp, and your own processing state where useful; the documented payload does not establish a universal unique event ID.
• Handle missing fields: optional data can be absent. Branch on the fields actually received instead of assuming every event includes HTML, labels, extracted data, or a PDF.
• Separate errors from changes: the webhook guide documents an event value of change for change alerts and error for error alerts. Route and log them separately.
• Protect receiver URLs: webhook URLs often act as credentials. Store them as secrets, restrict access, and rotate them if exposed.
• Keep an audit trail: record the job, URL, detection time, and processing result so operators can investigate missed or repeated workflow actions.

For a broader inventory, the documented listing endpoint is GET https://job.api.visualping.io/v2/jobs; its reference lists filters for active state, mode, frequency, event, date, URL/description search, and labels. The help page also says the API can update/delete monitors and retrieve changes, but endpoint paths and shapes for those operations should be taken from the live reference rather than guessed.

6. Rate limits, performance, and cost considerations

The API reference does not establish one fixed rate limit for every endpoint. It specifically documents GET https://job.api.visualping.io/v2/jobs/get-diff at 200 requests per rolling one-minute window; do not apply that number to the create or list endpoints. The reference says unlisted endpoints have no fixed published limit and that sustained abusive volume may still be restricted.

• On HTTP 429 / THROTTLED, pause and retry with exponential backoff and jitter; never spin in a tight retry loop.
• Keep polling and downstream work proportional to the workflow’s actual need. A webhook avoids repeatedly polling just to learn that a change occurred.
• Choose the monitor interval based on how quickly you need to know and what your account permits. The API reference’s listed default is once daily, with common interval examples down to five minutes; verify availability for your account.
• Capture only the page area and comparison mode you need. Narrow scopes can reduce irrelevant change alerts and the work your own consumer performs.
• Visualping subscription or usage costs are not specified in the cited API reference; check the current plan terms and account usage before choosing intervals or monitor volume. Do not infer price from request frequency alone.

Read the current rate-limit guidance before scaling. Its reference does not promise a general API stability guarantee or a fixed limit for every endpoint.

7. Troubleshooting

Symptom	Likely cause	Fix
HTTP 403 / AUTHENTICATION_FAILED	Missing/invalid Bearer header, expired or revoked key, or key put in query string	Send Authorization: Bearer … in the header, check expiration and key status, and never pass the key in the URL.
Key works for reads but monitor creation fails	Key has Read-only access	Create or request a Write-capable key for monitor creation.
Workspace is inaccessible or missing from results	Key scope does not include that workspace; Business create request may omit required workspaceId	Use a key scoped to the correct workspace or organization and provide the required workspace ID for Business.
Developer settings are unavailable	On a Business account, the user is not an Admin	Ask an account Admin to create the key or grant the required role.
HTTP 429 / THROTTLED	Rate limit exceeded	Back off exponentially, add jitter, reduce request frequency, and contact support before scaling a workflow that needs higher volume.
Webhook test fails or no event arrives	Invalid endpoint URL, receiver is unavailable, or webhook notification is not enabled on the job	Confirm the endpoint accepts the test request, enable Webhook in Notifications, then run Test again and check the receiver’s logs.
Screenshot, HTML, or optional key absent	Conditional field omitted because the feature or data does not apply	Check field existence before use. Confirm the job configuration and plan/support requirements for configured extraction.
Too many alerts from harmless changes	Full-page scope includes dynamic or unrelated regions; sensitivity is too low	Scope to a selector/crop, choose the relevant monitoring mode, or raise the threshold; review whether a preaction is needed for a stable page state.
Monitor appears stale or misses a short-lived change	Checks occur at intervals, and the page may change between them	Use an interval appropriate to the need and permitted by the account. Monitoring is not continuous observation; verify the schedule and page accessibility.
Lost the API key after closing its creation dialog	The key is only shown once	Delete that key and create a replacement, then update the integration secret.

Or skip the browser setup

If you need a direct website screenshot rather than a recurring Visualping monitor, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request captures a URL as an image or PDF; see the ScreenshotNeo API documentation.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Get started with 1,000 free screenshots a month, no card required.

FAQ

How do I use the Visualping API?

Create a suitably scoped API key, send it as a Bearer token, then call the documented jobs endpoint to create and configure a monitor. Configure webhook notifications when another system needs change events.

Can I request an immediate screenshot with the monitor endpoint?

The documented create-job call creates a monitor with a checking interval. Treat it as scheduled monitoring; use a screenshot API when the requirement is a direct one-off capture.

Can webhook events include extracted values such as a price?

The webhook guide describes extracted_data, but says custom extraction requires a Solutions plan and support configuration. Confirm availability before designing around it.

Where can I find exact update or change-history endpoint paths?

Use Visualping’s live API reference. The help overview confirms those capabilities, but endpoint paths and schemas should not be inferred from the create-monitor example.