Visualping API: Use Cases and Examples
See what the Visualping API can automate, how to create and manage monitors, and how to route detected changes into team workflows.
The Visualping API lets you manage website monitors from your own applications and workflows: create, update, and delete monitors, retrieve detected changes, and automate what happens after a check finds a change. A check is scheduled; detection and alerts follow that check, so this is not necessarily instantaneous monitoring.
Developers typically use it to watch a specific page or page element, define what change matters, and then route the resulting change into a review or notification workflow. This guide covers common use cases, the documented API workflow, authentication, alerts, limits, and practical implementation choices.
What can I use it for?
Use the API when a team needs to manage monitors programmatically or connect website changes to its own systems. Visualping names competitor changes, product listings, regulations, publications, jobs, property listings, and software releases among its monitoring use cases.
| Use case | What to monitor | Example response to a change |
|---|---|---|
| Competitor pricing and offers | A pricing, features, or promotion page; select the relevant region or element where possible. | Send the detected change to a shared review queue so someone can confirm the price or offer. |
| Retail availability | A product listing for a price or availability change. | Forward the change notification to an operations workflow. Custom structured extraction, such as price or stock status, requires Solutions-plan configuration. |
| Regulatory and compliance monitoring | Government or regulatory pages relevant to a team. | Route the resulting alert for internal review and retain the source page and comparison context. |
| Research and news | Journal, publication, newsfeed, or press-release pages. | Notify a research channel when a check detects changed material. |
| Jobs and real estate | Job listings, application dates, or property pages and prices. | Send a change to the hiring or property review process. |
| Software dependency updates | Vendor documentation, changelogs, and status pages. | Route a release, deprecation, or status-page change to an engineering team. |
| Multi-monitor reporting | Monitor listings and job activity across a set of monitors. | Retrieve activity and assemble an internal report using documented API operations. |
Visualping reports that, in a sample of active accounts, more than 73,000 users monitored price changes, 15,600+ monitored competitors, and 11,200+ tracked regulatory and compliance changes. The company also reported more than 19 million monitoring checks and 1.9 million change notifications in a 30-day window. These are vendor-reported sample-account figures, not independent market statistics. See the [Visualping use-case report](https://visualping.io/blog/website-change-monitoring-statistics).
What can the Visualping API do?
The official guide describes an API for integrating monitoring into applications and workflows. Its reference documents bearer-token authentication and account and job operations, including describing a user, listing jobs, creating jobs, reusing saved settings, bulk-creating monitors, and retrieving job activity or changes.
A monitor can specify a URL, description, mode, check interval, element selector, page actions, schedule, alert settings, and notification configuration. Choose these based on the signal you need and how the target page renders:
- Scope: monitor a whole page or a particular element with a selector.
- Signal: choose a visual, text, code, or configured extracted-data workflow as appropriate to the product setup.
- Timing: set the check interval and schedule. A change is detected when a check runs; an alert follows detection.
- Page preparation: add wait time or page actions where a page needs time to render or interaction before capture.
- Delivery: retrieve changes through the API or configure notification destinations and webhooks.
For endpoint paths, request fields, and current payload schemas, use the [Visualping API reference](https://github.com/visualping/visualping-api-reference) and [official API guide](https://help.visualping.io/en/articles/11913427-visualping-api-guide). The examples below use placeholders rather than inventing endpoint paths or request schemas: copy the exact path and JSON shape for the operation from the live reference.
Plan a monitor and its workflow
- Choose the precise URL. Prefer the page that contains the information of interest instead of a broad landing page. Confirm that it is publicly reachable by the monitoring service.
- Pick the monitored area. Use a selector when unrelated page changes would create noise. Use whole-page monitoring if the context around changes matters.
- Define the meaningful condition. Specify what a reviewer should consider actionable: a price change, a new feature, a changed rule, a release note, or a date update.
- Set page actions and waits. For dynamic sites, provide the documented page action or wait configuration needed for the target content to appear.
- Choose a schedule and interval. Match the cadence to the decision deadline. More frequent checks can surface a change sooner after it appears, but still do not make detection instantaneous.
- Choose delivery. Use API retrieval when your application owns the workflow. Use a webhook or a documented destination when an event-driven handoff is more suitable.
- Review a real detected change. Tune the selector, condition, and notification routing if the result includes irrelevant page changes.
Authentication and API key scope
The API reference specifies a bearer token in the Authorization header and recommends API keys. Keep the key in a server-side secret store or environment variable. Do not put it in a URL query string, path, browser code, or committed source file.
Choose the narrowest scope that supports the integration. Organization scope is intended for integrations spanning multiple workspaces; workspace scope limits access to one workspace. Read access is appropriate for retrieving information, while creating or changing monitors requires write access. The key guide recommends starting with read access and workspace scope when sufficient. Business-account Developer settings are limited to admins. Keys are shown only once, can be revoked, and are limited to five per organization.
Authorization: Bearer $VISUALPING_API_KEYFor a runnable request, use the exact documented endpoint and parameters for the operation you intend to perform. For example, to inspect the account or list jobs, copy the corresponding method, path, and response fields from the [API reference](https://github.com/visualping/visualping-api-reference), then supply the bearer header as shown below.
export VISUALPING_API_KEY="replace-with-your-key"
export VISUALPING_API_BASE="https://api.visualping.io" # Confirm the current API base in the official reference.
# Replace /DOCUMENTED/PATH with the exact path from the API reference.
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer ${VISUALPING_API_KEY}" \
-H "Accept: application/json" \
"${VISUALPING_API_BASE}/DOCUMENTED/PATH"The base URL above is a configuration placeholder, not a claim about Visualping’s current host. Confirm the base URL, endpoint path, HTTP method, content type, and JSON schema in the live reference before running a request. The reference is the source of truth for creating jobs, reusing saved settings, and bulk creation.
Examples: turn changes into useful actions
Competitor price review
Monitor the competitor’s pricing page or the relevant pricing element. Set a schedule that fits the team’s review window. When Visualping reports a change, retrieve its comparison context or route the notification to the commercial team’s shared review process. A person or downstream system can then verify whether the price, offer, or page wording changed in a meaningful way.
Retail availability workflow
Monitor the product listing and select the area containing price or availability. Configure a webhook or other supported notification route to deliver change context to an operations workflow. If the workflow needs a structured value such as a numeric price or stock status, check plan availability: Visualping describes custom structured extraction as a Solutions-plan feature. Do not assume a visual change notification is already a normalized inventory record.
Regulatory review queue
Monitor the relevant government or regulator page, and route changes to an internal reviewer. Keep the original URL and the comparison material with the alert so the reviewer can assess the context. Set the schedule according to the required review cadence; the alert follows a check, which may occur after the source page changed.
Engineering release watch
Monitor vendor changelogs, documentation, or status pages. Use element-level monitoring when a page contains unrelated updates, and route meaningful changes to the engineering channel or release review process. For multiple monitors, use the documented listing and activity operations to build a report; avoid relying on undocumented endpoint behavior.
Retrieve changes or receive webhooks
Use API retrieval when your application needs to poll or query monitor and job information as part of a controlled workflow. Use a webhook when a notification should be sent to your service after a change. Visualping documents webhook payloads as JSON containing monitor context and links to comparison material. The payload can include summaries and, when configured, extracted data.
Visualping names Zapier, n8n, and Microsoft Power Automate as common webhook destinations. Business plans list API, webhook, Google Sheets, Slack, and Microsoft Teams integrations. Verify current availability and plan requirements in the [webhook guide](https://help.visualping.io/en/articles/5780816-webhook-notifications) and [plan comparison](https://visualping.io/pricing) before designing around a destination.
For reliable webhook handling, make your receiver tolerant of duplicate delivery and transient failures: validate the request according to the current Visualping documentation, record the event identifier or stable event details you receive, acknowledge promptly, and process downstream work asynchronously. The cited reference material establishes JSON webhook notifications and destinations; confirm any signing, retry, and delivery guarantees directly in the current webhook documentation rather than assuming them.
Rate limits, performance, reliability, and cost
Rate limits and retries
The API reference documents HTTP 429 throttling. It recommends pausing and retrying with exponential backoff. It states that the get-diff endpoint is limited to 200 requests per rolling one-minute window; other endpoints have no fixed published limit in that reference, although sustained abusive volume may be restricted. Recheck the live reference before relying on exact limits because they can change.
# Retry policy outline for a client:
# 1. On HTTP 429, stop sending requests briefly.
# 2. Increase the delay exponentially on repeated throttles.
# 3. Add random jitter so concurrent workers do not retry together.
# 4. Cap the delay and surface persistent failures to operations.
# Honor any retry guidance returned by the current API.Performance and alert latency
End-to-end latency depends on the monitor’s schedule and the time needed to load the page and complete the check. A change just after a check may wait until a later scheduled check to be detected. Select a check cadence that meets the business need, and avoid requesting change data more often than needed; the documented get-diff limit applies to API retrieval, not to how often a source page changes.
Reliability practices
- Use a narrowly scoped API key and rotate or revoke it if exposed.
- Persist the monitor identifier and configuration in your integration so changes can be reconciled.
- Handle 429 responses with backoff, and distinguish a failed API request from a successful check that found no change.
- Make downstream notification handling idempotent where possible.
- Keep a human review path for changes with compliance, pricing, or operational consequences.
- Revisit selectors and page actions when the target site’s layout or rendering behavior changes.
Cost and plan fit
Plan choice depends on scale and workflow needs, not just the number of endpoints used. The cited plan comparison describes API, webhook, Google Sheets, Slack, and Microsoft Teams integrations on Business plans. It positions Solutions for higher-complexity managed deployments, custom output, large-scale use, onboarding, and support. Custom extraction such as price or stock status is described as a Solutions-plan capability. Check the current plan page for pricing and entitlements before budgeting.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| 401 or 403 response | Missing, invalid, revoked, or insufficiently scoped key. | Send the bearer token in the Authorization header, check that it is active, and confirm its workspace or organization scope and read/write access. |
| 429 response | Throttling, including the documented get-diff rolling-window limit. | Pause requests and retry with exponential backoff and jitter; reduce unnecessary polling and confirm current limit guidance. |
| Monitor misses the content | The relevant content is outside the selected area, loads late, or requires an interaction. | Review the selector, configure the documented wait or page action, and verify the target page and schedule. |
| Too many irrelevant changes | Whole-page monitoring includes dynamic or unrelated content. | Monitor a more specific element and tighten the condition or review criteria. |
| Alert arrives later than expected | Checks run on a schedule; the page may change between checks. | Choose an interval and schedule appropriate to the required response time, while accounting for load and check duration. |
| Webhook does not trigger expected downstream work | Receiver, destination configuration, or assumption about payload fields does not match the current setup. | Inspect the configured destination and actual JSON payload, confirm the documented fields, and check whether custom extraction is required for structured values. |
| API example returns not found or validation error | Placeholder path, method, or payload was used, or the reference changed. | Copy the current endpoint path, method, and schema from the official API reference; examples here intentionally do not invent endpoint details. |
Visualping API or a screenshot API?
Visualping is for scheduled website change monitoring: create monitors, define what to watch, and retrieve or route changes detected by checks. A screenshot API serves a different task: capture a page as an image or PDF on demand.
For screenshots, try [ScreenshotNeo](https://screenshotneo.com) first. It removes cookie and consent banners, newsletter popups, and chat widgets before capture, and only clean shots are billed. Its API also exposes whether a result was a bot check, blank page, failed load, or cache hit through response headers. See the [ScreenshotNeo API documentation](https://screenshotneo.com/docs/) for all request options.
Or skip the browser setup
If your workflow needs a screenshot rather than a scheduled change monitor, one GET request captures the page:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. 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. [Create a free ScreenshotNeo account](https://screenshotneo.com/account/sign-up/).
FAQ
Does the Visualping API detect a change instantly?
No. A change is detected when a scheduled check runs, and an alert follows that check.
Can I monitor just one part of a page?
The API reference includes an element selector option. Use it when only a specific page area matters, and verify the selector against the live page.
Can a webhook provide a price as a structured field?
Webhook payloads can include extracted data when configured, but custom structured extraction such as price or stock status is described as a Solutions-plan feature.
Can I use the API across multiple workspaces?
Organization-scoped keys are intended for integrations that need multiple workspaces. Workspace-scoped keys limit access to one workspace.
What if I only need a page image?
Use a screenshot API such as ScreenshotNeo for on-demand image or PDF capture; Visualping’s API is centered on managing monitors and detected changes.
