POST /v1/web/monitors creates a monitor: a set of targets checked on a schedule, from every 15 minutes to once a week. Each check compares what it reads with the last time and records what changed. Changes arrive as signed webhooks, an optional daily email, and a history you can read through the API.
Monitors are available on paid plans.
When to use it
- You watch a competitor’s pricing, a changelog, a status page or a policy and want to know the moment it changes.
- You want new posts, jobs or products from a site as they appear, without crawling it yourself.
- You want news, mentions or reviews of something as new results show up in search.
- You only care about some changes, like a price dropping below a number or a role in one city, and want the rest kept quiet.
Example request
monitor_create, monitor_list, monitor_changes, monitor_run, monitor_update and monitor_delete tools.
Targets
A monitor holds up to 10 targets, in any mix of the three kinds.Pages
{"type": "pages", "urls": [...]} watches up to 50 pages for changes to their content. A change comes with a line diff of the text and, when the page publishes them, the fields that moved, such as price, availability or a date.
CSS selectors, such as
#pricing or .plan-card. Only the content inside them is compared, so changes elsewhere on the page are ignored.Lines to leave out before comparing. Plain text matches anywhere in a line, ignoring case; wrap a pattern in slashes, like
/^Visitors: \d+$/, for a regular expression.Only alert when an added or removed line contains one of these. Every change is still kept in the history.
How each page is read, using the same options as Scrape, such as
location or waitForSelector.A whole site
{"type": "site", "url": "..."} lists the site’s pages on every check and reports pages that appear or go away. Each new page is read once for its title and opening lines.
The most pages to track, up to 1,000. When a site has more, new pages are still found, but none are reported as removed.
Read each new page once for its title and opening lines, up to 20 a check, at 1 credit each. Set
false to get the address only.A search
{"type": "search", "query": "..."} runs a search on every check and reports results it has never returned before. Results moving up or down, or dropping out, are not reported. A monitor with a search target checks at most once an hour.
What to search for, as you would with Search.
country, includeDomains and excludeDomains work as they do on Search.
Goals
Any target can carry agoal: what you are watching for, in plain words, up to 300 characters.
judge: null. Removed pages are not checked against the goal and alert as usual.
What counts as a change
- Changed: the text of a page differs from the last check. Relative times (“5 minutes ago”), clock times, view and like counts and tracking parameters on links are ignored, so a page that only shows a newer timestamp counts as the same.
- New: a page or search result seen for the first time after the first check.
- Removed: a page missing from two checks in a row, so one slow or broken read does not count as a removal.
- Error: a page that could not be read. Errors are never reported as changes. A page that fails three checks in a row sends one alert, and a monitor whose checks all fail ten times in a row pauses itself.
Checks and history
Checks run in the background.GET /v1/web/monitors/{id}/checks lists past checks, newest first, and GET /v1/web/monitors/{id}/checks/{checkId} returns one with every change it found.
POST /v1/web/monitors/{id}/run starts a check now, outside the schedule. PATCH /v1/web/monitors/{id} changes the name, targets, schedule, webhook or email setting, and {"status": "paused"} or {"status": "active"} pauses or resumes it. DELETE /v1/web/monitors/{id} stops it, and its history is deleted 30 days later.
History is kept for retentionDays, 30 by default and up to 365.
Webhooks
With awebhook, you get a call for each change and one when a check ends:
Set
webhook.events to ["change"] or ["completed"] to get only one of them. A monitor.change call carries the change as it appears in the history, plus monitorId, checkId and targetType:
webhook.secret and every call is signed the same way as crawl and batch webhooks. See Verifying a webhook.
Daily email
Set"email": "daily" and the workspace owner gets one email a day, at 08:00 UTC, listing what the monitor found in the last 24 hours. Nothing is sent on a day without changes, and owners who unsubscribe from account emails get none.
Limits
Billing
- Pages: 1 credit per page read. A page that cannot be read costs nothing.
- A site: 1 credit per check, plus 1 for each new page read.
- A search: 1 credit per check.
- A goal: 1 credit for each change checked against it, and nothing when it cannot be checked.
Related
Watch a site for changes
A worked setup, from choosing targets to handling alerts.
Jobs & webhooks
How webhook calls are signed and retried.
Credits
How every call is priced.
API Reference
Full monitor schemas and a live playground.