Skip to main content
POST
Preview Watch

Overview

Returns the number of trademarks that would have alerted if this query had been a live watch over the last trial_window_days (default 7). The preview evaluates the whole watch query: q, strategies, min_match_tier, filters and trigger_events, with the same match gate a live watch uses. Use it before Create Watch to estimate volume and tune strategies / min_match_tier for similarity watches. For a watch with a text query, the preview searches for q first and keeps the matches that changed in the window, so results are ordered by relevance and every row matched q. Requires the portfolios:manage scope.
Preview is a read-shaped operation, so the Idempotency-Key header is not required. Sending one, as in the example below, is always safe.

Body Parameters

object
required
Same DSL as Create Watch, see the query reference. ID-bearing filters (filters.trademarkIds, filters.ownerId, …) accept the same tm_* / own_* prefixed forms as create.
integer
Backtest window in days (1-365). Default 7.
boolean
Skip the matching marks and return just estimated_match_count. Default false.
integer
Page size for results (1-50). Default 20. Ignored when count_only is true.

Response

string
Always "watch_preview".
integer
Trademarks that would have alerted in the trial window.
array
A page of the actual matching trademarks, in the same summary shape as search results. Omitted when count_only is true.
boolean
Whether more matches exist beyond results. Omitted when count_only is true.
integer
Effective page size used for results. Omitted when count_only is true.
string
Present only when estimated_match_count is not an exact count. Absent when it is exact.
  • lower_bound: the search timed out, more than 10,000 marks matched q in the window, the check against the window’s changes timed out, or the re-check of marks changed in the last 6 hours (changes the search index may not reflect yet) could not finish. The count is the matches the preview verified (0 if none); the real number can only be higher.
  • query_upper_bound: the time budget ran out after the search but before the check against the window’s changes. The count is the marks that matched q in the window plus the marks changed in the last 6 hours that the search index may not reflect yet; the real number can only be lower.
  • candidacy_upper_bound: a watch without a text query could not be fully evaluated (search unreachable, a very large set of changes, or the time budget ran out). The count is the number of changed marks in the window.
results always holds verified matches only.
boolean
Present and true when the preview did not finish: the time budget ran out, the search timed out or lost a shard, or the page of results could not be loaded (then results is empty and has_more is false, but the count stands). The count and estimate_basis describe what was evaluated.
integer
Echo of the requested window.
string
Request identifier.

Latency and limits

Preview runs synchronously with a server-side time budget of about 20 seconds, and each database read inside it is capped at 10 seconds. mark and owner previews and narrow class previews typically complete in a few seconds; similarity previews over broad scopes and long windows are the heaviest and can approach the 20 second budget. A watch without a text query is scoped in the database first, so a broad one (for example a class watch on one class in US over 30 days) can hit the 10 second read cap and return 504 after about 10 seconds.
  • For a watch with a text query, a timeout returns 200 with partial: true, the verified count and an estimate_basis. If search is unavailable the response is 503 service_unavailable (retryable).
  • For a watch without a text query, a budget that runs out after candidates were found returns 200 with partial: true; one that runs out before any usable result exists returns 504 (see Errors).
  • Concurrent previews are limited per organization; exceeding the limit returns 429 with a Retry-After header. See Rate limits for header semantics.

Errors

504 preview_timeout

Code Examples