Watches

Save a search once — “new running shoes under £100”, or just “anything new here” — and hear only when a record matches that you have not been told about.

• Never sends the same result twice. An unchanged list sends nothing; a list that gains one record sends one alert.
• Belongs to one list and searches only that list.
• Found on a list under the bell (Watches) icon in its header.

New or changed

A record alerts you when it is new to the watch, and again whenever its content changes — a price drop, stock coming or going, a rewritten description.

• Content means the record’s name and fields.
• Not the time it was last saved — re-importing the same data sends no alerts. Exception: on a list bigger than the watch’s memory (at least 500 records), a re-import makes forgotten records newest again, and they alert again.
• Not the relevance score, which moves with the search rather than the record.

Why a watch pins a version

A watch pins one version of its list, as an eval set does.

• A version fixes the list’s fields — the facets and searchable fields your search and filter name — so a later rename or drop cannot change what your filter means.
• Records are never versioned. A new record shows up in every version the moment it lands, so a watch on an older version still sees everything new.

Create a watch

Press Create watch on the list’s Watches page. Only a name is required; the list version, filter, check every and max alerts per check sit under Advanced, already defaulted. The watch starts on the next check run.

• No silent start. The first check alerts on records that already match — up to max alerts per check, newest first.
• Attached index refused. Creating a watch on an attached list fails with code 6.
• A vetted watch is stored paused for a moment while its judge is set up, so no check runs it unvetted.
• Two creates of one name at once: one wins, the other gets code 2.

Checking alerts with a judge

Each new or changed record goes to the chosen model before it counts as an alert. A judge can decide “only if the item is under £100 and in my size”; a search cannot.

• No judge to set up first: the watch writes its own instructions, billed to that key. A watch created through the API can name instructions you wrote; the console shows them and leaves them alone.
• Only new or changed records are judged, so an unchanging list costs nothing however often it checks. A record ruled out is remembered as ruled out and is not judged — or billed — again.
• No decision on a record (a refusal, a badly shaped answer, a bad minute) — the record is still sent, marked needs review, unless the whole check fails (below).
• 4 minutes to judge per check. Records ruled on in time count; the rest are judged at the next check, not marked needs review.
• Judge cannot rule at all (rejected key, a model that key may not use, the judge deleted or replaced) — the check fails and nothing is marked as seen, so those records alert properly once you fix it.
• Provider unreachable or busy (timeout, 429, 5xx) before any record is judged — the check fails the same way, as an outage that retries on the next tick.
• Judge answers but rules on none (3 records refused or badly shaped before any is judged) — the check fails with the judge’s error and waits the interval.
• A blip loading the judge is also retried on the next tick.
• Providers grant models per project and plan, so a documented model is not always one your key can call. The judge’s health indicator reads your key’s own model list and turns red on a model it cannot use. Fix it with another model, or a key with access.

Getting alerts

Every alert is recorded in the watch’s Alerts feed (its … menu → Alerts), newest first, whether or not anything is emailed.

• Each is stamped with the version of the list searched and the revision of the watch that found it, so an old alert still says which records were included and which question was asked.
• Outside the console: email for a person, webhooks for a machine — independent of each other.

By email

• At most one email per check interval. Matches found in between (by Check now or an instant check) join the next email. Nothing found, nothing sent.
• The email names up to 10 records plus the total count; every alert is in the Alerts feed.
• Everyone listed gets their own copy, so each can unsubscribe alone and nobody sees another’s address.
• If the email to one address fails while others go out, that address misses that email and it is not resent; the alerts stay in the Alerts feed.
• Up to ten addresses per watch. Need more? A group address counts as one.
• An address containing ; is refused as not looking like an email address.
• Every email carries a stop emailing me link, personal to its recipient (plus one-click unsubscribe headers). It stops mail to only that address, on every watch in the account; the watches and their webhooks keep running.
• An address that unsubscribed stays listed on the account’s other watches but gets no mail there. It can’t be added back to the account’s watches.

By webhook

Send alerts to a webhook by subscribing to either event, or both:

• status: needs-review = the judge couldn’t decide; send it to a person.
• The message carries the record’s id, not its fields: the record is live, so fetch it by id.

Is it telling you useful things?

Every alert has a thumbs-up and a thumbs-down, building the watch’s precision: of the alerts you rated, the share you actually wanted.

• Measured, never learned from — nothing re-ranks, re-tunes or filters on your ratings. Low precision means the watch is asking the wrong question — edit the search, or tighten what you asked the judge for.
• Rating the same record twice replaces the earlier rating: one rating per record.
• Sent to your telemetry destination as searchstack.watch.precision, alongside searchstack.watch.matches, searchstack.watch.judge.filtered and searchstack.watch.sweep.duration. Sweep duration is per account, not per watch.
• The searches a watch runs are counted in searchstack.search.* with origin="watch".

Editing and pausing

• Edit is a full replace, not a partial update. It moves the watch to its next revision, so alerts either side of an edit can be told apart, and never re-alerts records already reported.
• Move to a newer list version by changing the pinned version in an edit. Leave the version out and the current pin is kept.
• A different list is not possible — that would lose the watch’s memory. Delete the watch and create another.
• Pause stops the checks and keeps the watch and its history. A paused watch is never checked.
• Editing the search or criteria does not re-check records already seen. A record ruled out stays ruled out until its content changes.

Checking now

A watch’s … menu → Check now runs the check immediately.

• The same check, not a preview: it really searches, judges, records alerts and sends the emails and webhooks. There is no test run — pause a watch you are still deciding about.
• Refused on a paused watch. Resume it first.
• On an attached index it never searches. Each check records search_failed; delete the watch.
• Records already alerted are not sent again; a check over an unchanged list costs one search and no judging.
• Runs in the background. The row says Checking now… and updates Last checked when the result lands, usually within seconds — or shows Failed.
• Resets the timer for the next scheduled check — a daily watch checked at noon next runs around noon tomorrow. After an outage it changes nothing — Last checked stays as it was.

When a check fails

A check that cannot run shows Failing on the watch and Failed under Last checked; its Alerts open with the reason.

• Nothing is marked as seen, so no alert is lost. The next check tries again.
• From the API: last_outcome, last_error and last_error_utc on watch_view and watch_list. A check that runs sets ok and clears the error.
• All three are null before the first check, and again after an edit that changes the list version, search, filter, vector search, criteria or judge — including the watch’s judge recreated on another key. A watch on an attached index keeps search_failed through such an edit.
• A temporary failure — engine unavailable, the hourly search limit, or the judge’s provider unreachable or busy — shows the failure but leaves last_swept_utc unchanged, so the next 15-minute tick retries.
• Those retries stop 1 hour past the check’s due time; after that the watch waits its interval. A broken judge waits the interval at once.
• Check now or an instant check on a watch not yet due that hits a temporary failure is re-checked once, 15 minutes later; after that it waits its schedule.
• A check that never started changes nothing: last_swept_utc and last_outcome keep their values. If another check was running, the next timer tick tries again; if the list or the watch’s memory could not be read, it is retried within minutes.

How fast

Watches are checked on a 15-minute timer. A watch runs when its check every interval has passed since its last check finished, so a 15-minute watch may run only every 30 minutes.

• Instant checks on lists SearchStack hosts: a write that matches the watch’s search and filter triggers a check within about a minute (never sooner than a minute after the last one).
• Instant checks use the list’s synonyms. After an engine restart they resume within about 30 minutes.
• Instant checks ignore check every. During steady ingest a watch is checked about once a minute — one search each, plus judging and a watch.digest for every check that finds something.
• A slow engine doesn’t hold a save. Create, edit and delete wait at most 5 s to register or remove instant checks; past that, the next 15-minute sweep finishes it.
• Timer only: vector-search watches, and lists on other backends.
• Not yet on an attached index (e.g. Azure AI Search): a check orders records by last-modified time, which an attached index can’t map yet. Create is refused; an existing watch shows search_failed without spending a search.
• Emails stay at most one per interval; matches from instant checks join the next email.

From the API

Every watch action is on the public API and the MCP tools. Shapes in the API reference.

• Pause or resume: edit replaces every field, so send back everything from watch_view with only enabled changed. A left-out field reverts to its default — no notify_emails means no email, no judge means no vetting. Left out, enabled and list_version keep their current values.
• Check every (interval_minutes): 15 or more through the API; the console offers up to 24 hours.
• Alert history is trimmed to the newest 1,000 alerts and the last 90 days, at most once a day, when the watch records a new alert. A watch that stops alerting keeps its history until you delete it.
• Refusals carry a code in the problem body:

Limits

• Name: letters, digits and single hyphens, up to 100 characters.
• Search text up to 1,000 characters, criteria up to 16,000, filter up to 16 KB and 200 conditions.
• Every check — timed, instant or Check now — uses one search from your plan’s search allowance.
• 25 watches checking every 15 minutes is about 50 timed searches an hour (each runs about every 30 minutes). During steady ingest, instant checks add up to one search a minute per watch.

Deleting

Deleting a watch removes its alert history and your ratings. Your records are untouched — a watch only ever reads. Deleting the list deletes its watches.

What a watch is not

• Not instant. An instant check can still lag a write by about a minute — see How fast.
• Not a copy of your data. It keeps each alerted record’s id, name and the judge’s verdict, never its fields.
• Not a learning system. Nothing acts on your ratings but you.