> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.repliers.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Saved Searches: The Initial Match Limit, Why It Exists, and How to Build Around It


This guide explains how saved search alerts work, why there is a cap on the number of initial matches, what the 406 error means, and the UX patterns we recommend so that your users never run into the limit at all.
## How saved search alerts actually work

There are two distinct phases in the life of a saved search, and most confusion about the system comes from conflating them.

**Phase 1 — Creation or update.** When a saved search is created or updated, the API evaluates the filters against current inventory. If the *initial* match set exceeds the account's cap (100 by default), the request is rejected with a **406 (Not Accepted)** response and the search is not saved (or the update is not applied). This is a one-time validation on the request itself.

* Create a saved search: https://docs.repliers.io/reference/create-a-saved-search
* Update a saved search: https://docs.repliers.io/reference/update-a-saved-search

**Phase 2 — Ongoing alerts.** Once a saved search exists, alerts are **event-driven going forward**. Matches are generated as listings are newly added, change price, or sell, according to the search's `notificationFrequency`, `priceChangeNotifications`, and `soldNotifications` settings. Existing inventory is not backfilled and re-sent. A saved search covering a slow-moving segment may legitimately send nothing for a while — that is expected behavior, not a broken search.

Full implementation guide: https://help.repliers.com/en/article/saved-search-implementation-guide-1pomr3h/

An important consequence: the cap does **not** limit how many alerts a search can send over its lifetime. A search created with 40 initial matches can go on to alert on hundreds of new listings over the following months. The cap only governs how broad the search is at the moment it is saved or updated.

## Why ambiguous searches are not supported

The cap exists to protect both the platform and the end user from ambiguous searches — filter sets so broad that they don't express a real intent.

From the user's perspective, a search that matches many hundreds of listings on day one will also match a proportionally large stream of new listings, price changes, and sales going forward. The result is a noisy alert flow that quickly trains the user to ignore the emails, and eventually to unsubscribe. An alert channel is only valuable if what arrives in it is relevant, and relevance requires refinement. A search that a user genuinely intends to act on is almost always narrower than the raw "everything in this county under $700k" query they might start from.

From the platform's perspective, ambiguous searches multiply matching and delivery work across every listing event in a large geography, degrading the timeliness of alerts for everyone. The create-time check is the cheapest, most predictable place to enforce specificity: it fails loudly, once, at the moment a human (or your integration) can respond to it — rather than silently throttling delivery later.

For these reasons the cap can be **raised on request** (for example to 1,000) where your use case warrants it, but it cannot be removed entirely. If you believe your account needs a higher cap, contact support.

## The most common failure mode: silent 406s from automated updates

The single most damaging pattern we see is an integration that creates or updates saved searches programmatically **without checking the API response**. A background job (for example, a cron that "optimizes" or re-aligns saved searches to user behavior) broadens a search, receives a 406, ignores it, and moves on. From that point the search either doesn't exist or is stuck on stale criteria, and nobody notices until a client asks why they stopped receiving listings.

Treat a 406 on create or update as a first-class application error, never as noise. At minimum your integration should log it, alert your team, and leave the previous known-good search untouched. If your workflow automatically rewrites search criteria, validate the new criteria first (see below) and only apply the update after validation passes.

## Recommended UX and integration practices

**Validate before you save.** Before calling create or update, run the candidate filters as a normal listings query and check the result count. If the count is over your account's cap, don't attempt the save — guide the user to refine instead. This turns the cap from a runtime error into an ordinary piece of UI state.

**Disable the "Save Search" button until the search is specific enough.** The pattern that works best in practice is to keep the save button disabled while the current result count exceeds the cap, paired with a live count and a short prompt such as "Narrow your search to under 100 results to enable alerts." The user refines with the map, price band, beds/baths, or property type until the button activates. A video demonstration of this pattern is available here: https://www.loom.com/share/87a7c3b762ce4c9f98d09b84dbb58bc2. This removes the need to educate every agent and lead about the constraint — the interface enforces it invisibly.

**Design price bands around live counts, not fixed widths.** Inventory density varies enormously by area and segment, so a fixed band width (say $25k) will be too narrow in some markets and too wide in others. Use the pre-save count query to size each band dynamically so it lands comfortably under the cap, and be aware that segments heavy in new-construction or high days-on-market listings will be denser than they look.

**Fail visibly, and monitor search health.** Surface save/update failures to the user or agent in the moment, and consider a periodic health check that verifies each active saved search still exists and reflects its intended criteria. A search that silently disappeared or regressed weeks ago is far more costly than one that failed loudly today.

**Set expectations about quiet periods.** Because alerts are forward-looking only, a healthy, well-scoped search can go days without sending anything if there's no new activity in its segment. Consider showing users when their search last matched something, so silence reads as "no new inventory" rather than "broken."

## Quick reference

| Question | Answer |
| ---- |
| What does the cap apply to? | The number of listings the filters match at create/update time only |
| What happens if it's exceeded? | The API returns 406 (Not Accepted) and the search is not saved/updated |
| Does the cap limit ongoing alerts? | No — alerts after creation are event-driven and uncapped |
| What is the default cap? | 100 initial matches |
| Can the cap be raised? | Yes, on request (e.g., to 1,000); it cannot be removed entirely |
| Why does a search send nothing? | No new listings, price changes, or sales have matched it — alerts are not backfilled |
| Best way to avoid 406s in the UI? | Show a live result count and disable "Save Search" until the count is under the cap |
| Best way to avoid 406s in automation? | Query the count first; only create/update after validation passes, and treat any 406 as an actionable error |