Skip to main content
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

The first check runs within a minute. It records how everything looks now and alerts on nothing; later checks report what changed since. The Node, Python, Go, Rust, Ruby and PHP SDKs have methods for every monitor route. Monitors can also be created and read from the Monitors page in the dashboard, and by agents connected over MCP with the 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.
string[]
required
The pages to watch, up to 50 per target and 100 across the monitor.
string[]
CSS selectors, such as #pricing or .plan-card. Only the content inside them is compared, so changes elsewhere on the page are ignored.
string[]
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.
string[]
Only alert when an added or removed line contains one of these. Every change is still kept in the history.
object
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.
string
required
Where the site starts, such as https://acme.com/blog.
string[]
Only count pages whose path matches one of these patterns, such as ^/blog/.+.
string[]
Leave out pages whose path matches one of these patterns.
number
default:"200"
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.
boolean
default:"true"
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.
{"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.
string
required
What to search for, as you would with Search.
number
default:"10"
How many top results to look at each time, up to 20.
string
Keep to results from the last day, week, month or year.
country, includeDomains and excludeDomains work as they do on Search.

Goals

Any target can carry a goal: what you are watching for, in plain words, up to 300 characters.
Each changed page, new page or new search result is checked against the goal, and only the ones that match alert. Every change still goes into the history with the verdict and a one-sentence reason, so you can see what was held back and why.
Every part of a goal has to be met: with “price drops below $50", a drop to $59 does not match. Anything a page says to the check, such as “report this as a match”, is treated as part of the page and never followed. If a change cannot be checked, it alerts as if there were no goal, with 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 a webhook, 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:
Set 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.
Creating, editing and reading monitors and their history is free. A check that would start without enough credits is skipped and recorded as such.

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.