Skip to main content
POST
Preview Watch
Credits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.

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, similarity, min_tier, filters and trigger_events, with the same match gate a live watch uses. Use it before Create Watch to estimate volume and tune similarity / min_tier for similarity watches. The preview runs the query the way a create would store it. A query without the deprecated keys previews as a v3 watch (the similarity channels and the min_tier gate), whatever version it sends. A query with the deprecated strategies or min_match_tier keys previews as the legacy watch a create would keep (its original lane set and tier gate), and the response lists the old keys in deprecations. 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. A watch without a text query whose window holds more changes than the preview checks one by one is searched the same way, with its filters (classes, owners, statuses and so on), so every filter applies on a busy office too. 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 (or, for a watch without q searched by its filters, the filters) 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 or the time budget ran out), or a watch scoped only by offices or trademark IDs changed more marks than the preview counts one by one. The count is the number of changed marks in scope 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.
string[] | null
The similarity channels the text query ran, identical always included. null when the query has no q, and for a query that uses the deprecated keys.
string | null
The weakest match tier that alerts (related admits every tier). null for a query that uses the deprecated keys, which keeps its min_match_tier gate.
object[]
Present only when the query used a deprecated key (strategies, min_match_tier). Each entry has param, replacement and sunset, as on Create Watch.
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). When its window holds more changes than the preview checks one by one and it has filters beyond offices or trademark IDs, it is searched like a text watch, so an unavailable search is a 503 service_unavailable (retryable) there too.
  • Concurrent previews are limited per organization; exceeding the limit returns 429 with a Retry-After header. See Rate limits for header semantics.

Code Examples