Watch a page for changes
writ_create_monitorCreate a scheduled monitor to watch a URL for changes in page content, a CSS selector's text, or a visual zone, and fire a change_detected event. Returns a monitor id for alerts.
Instructions
Create a MONITOR — a target Writ checks on a schedule and that fires a change_detected event when the page, a CSS selector's text, or a visual ZONE of the page changes. Use when the user wants to WATCH a URL for changes/updates. Returns the monitor id for writ_wire_monitor.
PROVE THE SELECTOR FIRST: open the page with writ_browser_use and pass its session_id — the selector is checked on the live page before saving. One that matches SEVERAL elements (Amazon '.a-price' matches a dozen; the check would join them into one blob) is pinned to the one shown; one that matches nothing or only an image becomes a VISUAL ZONE watch. NO SELECTOR FOUND AT ALL? mode='visual' + zone_text=<the value exactly as the page prints it, e.g. '51,77 EUR'> watches that area's pixels (digits are compared, so 51.77 finds '51,77 EUR'). A zone fires on ANY visual change — wire a change alert, not a threshold. selector_check in the answer says what was done.
HOW OFTEN + ACCOUNT: no interval → needs_input (this plan's options + a tell_user to relay; nothing created); one the plan refuses is refused with the allowed ones. The page is read first: behind a sign-in → needs_persona; a bot check → it offers use_residential.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to monitor (required). | |
| mode | No | 'visual' watches the on-screen ZONE of `selector`'s element (or of `zone_text`) and diffs its pixels — for charts, images, badges, or a value no selector can read. | |
| watch | No | 'price' also rejects a selector whose text holds no number (it becomes a zone). Default 'content'. | |
| device | No | A linked Writ desktop's agent_id (writ_devices): act ON it. Omit to use the desktop this connection chose with writ_devices action='use' (if any). | |
| enabled | No | Start the monitor enabled (default true). | |
| extract | No | BROWSERLESS alternative to `selector`: a response-extraction spec the check applies to a plain HTTP response — {"from":"json","path":"data.price"} (a JSON/XHR endpoint, with request_url), {"from":"html_css","selector":".a-offscreen"} (the page markup), {"from":"regex","pattern":"..."} (a value in a script/JSON blob). PREFER it over `selector`/requires_browser whenever the value is readable without JavaScript — most prices and stock lines are: no browser at any check, cheaper, and harder to wall. Best first: structured data (an endpoint, JSON-LD, a JSON blob) survives a redesign. Same grammar as api_call response_extractions. | |
| interval | No | How often to check: an option id from the needs_input answer ('5m', '15m', '1h', '6h', '24h') or a number of seconds (3600). Omit it and the answer is needs_input: this account's options (checks a day, how long the check allowance lasts, allowed or which plan) and a tell_user to relay — ask the user, then call again with their pick. An interval the plan refuses is refused with the allowed ones; one that runs the allowance out before it renews is created with a `warning`. | |
| selector | No | CSS selector for content-change monitoring; omit for uptime/status monitoring. | |
| zone_text | No | The text the page PRINTS where the value is (e.g. '51,77 EUR', 'Currently unavailable'). Locates the zone when no selector exists. | |
| persona_id | No | Every check carries this persona's LIVE session (kept fresh by the persona's own sign-in), so a login or a bot wall it passed stays passed (writ_personas). Only for a page behind a sign-in: a public page is watched without one, and the answer says when one is needed. | |
| session_id | No | An open writ_browser_use session on this page. The selector is proved there before saving (pinned / switched to a zone); REQUIRED for mode='visual' or zone_text. | |
| try_anyway | No | After a bot-check answer: create it on Writ's servers anyway (a check that meets the bot check reads nothing). | |
| request_url | No | With `extract`: the endpoint the value comes from (an XHR the page calls), when it is not `url` itself. | |
| use_residential | No | Check through a residential exit — for sites that wall datacentre traffic (Amazon, marketplaces). A bot check found on the page is answered with this offer, or with the alternatives when the plan cannot pay for one. | |
| interval_minutes | No | Legacy: how often to check, in minutes. Prefer `interval`. | |
| requires_browser | No | Render with a real browser (JS) instead of plain HTTP. Set it for JS-rendered/SPA pages and framed pages (framesets/iframes): the check matches the rendered, frame-flattened DOM, and selector validation is deferred to the first browser render instead of a raw-HTML fetch. Omitted, a page the access check could only read in a browser is checked in one. | |
| residential_country | No | ISO-2 exit country for use_residential (e.g. 'ca'); implies use_residential. |