Watches

A watch is a search you only have to run once. You save the question (“new running shoes under £100”, or simply “anything new here”) and Search Stack re-runs it for you on a cadence you choose. When something turns up that it has not already told you about, it tells you.

The word doing the work there is already. A watch does not send you the same result twice. It remembers everything it has alerted you on, so a list that is not changing produces silence, and a list that gains one record produces exactly one alert. That is the whole feature: ask once, hear only about what changed.

A watch is a property of a list — you create and manage it from the list’s own Watches dialog (the bell icon in the list header). A watch asks its question of one list.

Why it matters

The usual way to find out that something new arrived in your data is to keep looking: a saved search someone re-runs each morning, a dashboard nobody opens, a cron job that emails you the same fifty rows every night until you filter it to death. All of these have the same problem. They tell you what matches, not what is new, so you do the diffing in your head and eventually stop reading them.

A watch does the diffing. It is the difference between a report you have to scan and a message you can act on.

Why a watch pins a version

A watch pins one version of its list, the same way an eval set does — but for its own reason. A list version is a field shape: the facets and searchable fields your filter and query refer to. Pin a version and a later schema change — a renamed facet, a dropped field — can’t silently change what your watch’s filter resolves against. The question keeps meaning what it meant when you wrote it.

Pinning costs you nothing in freshness. Records are never versioned — a new record is visible in every version of the list the moment it lands — so a watch pinned to an older version still sees every new record. You migrate the pin when you are ready, by editing the watch. By default a new watch pins the list’s current version, which is almost always what you want.

Create a watch

1. Open the list you want to watch and click the bell (Watches) icon in its header. In the Watches dialog, click Create watch.
2. Give it a name.
3. Pick the list version to pin. It defaults to the current version — leave it there unless you have a reason to watch an older schema.
4. Type what to ask for. Leave it blank to hear about anything new in the list, which is what you want when you are mirroring a feed.
5. Optionally add a filter, set how often to check, and cap records per check.
6. Optionally pick a judge and write your criteria under Only alert me if….

That is it. The watch starts on the next sweep.

Vetting alerts with a judge

A query gets you close. A judge gets you the rest of the way.

Name a judge and write criteria, and every record the watch finds fresh is put to your LLM before it counts as an alert. “Only alert me if the item is under £100 and in my size” is not something a query can express — but it is exactly what a judge can rule on.

Only new records are ever judged. The watch diffs first and judges second, so a watch over a list that is not changing costs you nothing at all, however often it checks. A record the judge rules out is remembered as ruled-out, so it is not re-judged (and re-billed) on every check.

If the judge cannot reach a verdict on a record (your provider had a bad minute), the record is still delivered, flagged needs review. A watcher must never silently not be told about something because an LLM timed out. If the judge is unusable entirely — a rejected API key — the check is skipped and nothing is marked as seen, so once you fix the key those records alert properly rather than being lost.

Getting alerts

Each alert is recorded in the watch’s Alerts feed (its kebab menu → Alerts), newest first. Every alert carries two stamps that matter later: the version of the list that was searched, and the revision of the watch that found it. Months on, those two say exactly which records were in scope and which question was being asked — even though both may have moved on since. An alert stays interpretable.

To be told outside the console, subscribe a webhook to either event:

Pick whichever suits; subscribing to both delivers both. The payload carries the record’s id, not its fields — the record is live, and a copy on the wire would be stale the moment it was sent. Fetch it by id to see it now.

Is it telling you useful things?

Every alert has a thumbs-up and a thumbs-down. Rating them builds the watch’s precision: of the alerts you ruled on, the fraction you actually wanted.

This is measured, never learned from. Nothing re-ranks, re-tunes or filters on your ratings, and the watch will not quietly start second-guessing your query. The number exists for one reason: a watch showing you mostly-dismissed records is asking the wrong question, and that should be visible to you — the only person who can fix it. Edit the query, or tighten the criteria.

Rating the same record twice replaces the earlier rating rather than counting it twice, so the tally is always one judgement per record. Precision is also exported as searchstack.watch.precision to your telemetry destination, alongside searchstack.watch.matches, searchstack.watch.judge.filtered and searchstack.watch.sweep.duration.

Editing, re-pinning and pausing

Edit re-tunes what a watch asks. It is a full replace, not a patch — the request says what the watch asks now — and it bumps the watch’s revision, so alerts found before and after stay distinguishable. Editing never re-alerts what the watch already told you about.

Editing is also how you migrate the pin: change the pinned version to move the watch onto a newer schema when you are ready. Omit the version on an edit and the current pin is kept.

You cannot repoint a watch at a different list. That would strand its memory and re-alert the new list’s entire result set; it is a delete and a create.

Pause stops the checks without losing the watch or its history. A paused watch is never swept.

Limits

A check spends one search from your plan’s search allowance, like any other search. At 25 watches on a 15-minute cadence that is 100 searches an hour — a rounding error against a paid plan’s allowance, but it is your allowance.

Deleting

Deleting a watch takes its alert history and your ratings with it. Your records are untouched — a watch only ever reads. Deleting the list a watch points at deletes the watch too.

What a watch is not

• Not a live trigger. The cadence is minutes, not milliseconds. A watch is for “tell me about this today”, not for driving a real-time workflow.
• Not a copy of your data. It stores what it alerted you on, not what your records said. Alerts point at live records.
• Not a learning system. Your ratings are measured and shown back to you. Nothing acts on them but you.