Preview Watch

Dry-run a watch query: get a match count without creating a watch

POST /v1/watches/preview

Preview Watch

cURL

curl --request POST \
  --url https://api.signa.so/v1/watches/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": {},
  "trial_window_days": 123,
  "count_only": true,
  "result_limit": 123
}
'

import requests

url = "https://api.signa.so/v1/watches/preview"

payload = {
    "query": {},
    "trial_window_days": 123,
    "count_only": True,
    "result_limit": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: {}, trial_window_days: 123, count_only: true, result_limit: 123})
};

fetch('https://api.signa.so/v1/watches/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.signa.so/v1/watches/preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => [
        
    ],
    'trial_window_days' => 123,
    'count_only' => true,
    'result_limit' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.signa.so/v1/watches/preview"

	payload := strings.NewReader("{\n  \"query\": {},\n  \"trial_window_days\": 123,\n  \"count_only\": true,\n  \"result_limit\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.signa.so/v1/watches/preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {},\n  \"trial_window_days\": 123,\n  \"count_only\": true,\n  \"result_limit\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.signa.so/v1/watches/preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {},\n  \"trial_window_days\": 123,\n  \"count_only\": true,\n  \"result_limit\": 123\n}"

response = http.request(request)
puts response.read_body

Exact count

{
  "object": "watch_preview",
  "estimated_match_count": 17,
  "trial_window_days": 30,
  "request_id": "req_8mQ2vXpL"
}

{
  "object": "watch_preview",
  "estimated_match_count": 50000,
  "estimate_basis": "candidacy_upper_bound",
  "trial_window_days": 30,
  "request_id": "req_4nRvXq2T"
}

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). Uses the same evaluation logic as a live watch, so the count is a faithful preview, not a separate query engine. Use it before Create Watch to estimate volume and tune strategies / min_match_tier for similarity watches.

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

query · 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.

trial_window_days · integer

Backtest window in days (1-365). Default 7.

count_only · boolean

Skip the matching marks and return just estimated_match_count. Default false.

result_limit · integer

Page size for results (1-50). Default 20. Ignored when count_only is true.

Response

object · string

Always "watch_preview".

estimated_match_count · integer

Trademarks that would have alerted in the trial window.

results · array

A page of the actual matching trademarks, in the same summary shape as search results. Omitted when count_only is true.

has_more · boolean

Whether more matches exist beyond results. Omitted when count_only is true.

result_limit · integer

Effective page size used for results. Omitted when count_only is true.

estimate_basis · string

Present only when estimated_match_count is an upper bound rather than an exact count (the value is "candidacy_upper_bound"). This happens when the underlying scan is large enough to hit the server-side cap, or the time budget runs out after some matches were already found. Absent when the count is exact.

trial_window_days · integer

Echo of the requested window.

request_id · string

Request identifier.

Latency and limits

Preview runs synchronously with a server-side time budget of about 20 seconds. class, mark, and owner previews typically complete in a few seconds; similarity previews over broad scopes and long windows are the heaviest and can approach the budget.

• If the budget runs out after some matches were found, the response is a 200 with a partial count and estimate_basis: "candidacy_upper_bound".
• If it runs out before any usable result exists, the response is a 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

Status	type	When
400	validation_error	Invalid query (see Create Watch)
413	payload_too_large	query payload exceeds 256 KB
429	rate_limited	Another preview is already running for your organization, or the server’s preview capacity is saturated. Honor Retry-After (about 20 seconds); the SDK retries automatically.
504	preview_timeout	The time budget expired before any usable result existed. The response carries retryable: false; narrow the query (fewer offices, shorter trial_window_days, tighter filters) instead of retrying.

504 preview_timeout

{
  "error": {
    "type": "preview_timeout",
    "title": "Preview Timeout",
    "status": 504,
    "detail": "The preview could not produce a result within the server-side time budget.",
    "suggestion": "Narrow the watch query, add office or jurisdiction filters, reduce trial_window_days, or scope filters.trademarkIds, and retry.",
    "retryable": false
  },
  "request_id": "req_8mQ2vXpL"
}

Code Examples

cURL

curl -X POST "https://api.signa.so/v1/watches/preview" \
  -H "Authorization: Bearer sig_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: preview-owner-watch-2026-06-12" \
  -d '{
    "query": {
      "version": "v2",
      "filters": { "ownerId": "own_7pQmX3Lv" }
    },
    "trial_window_days": 30
  }'

import { Signa } from "@signa-so/sdk";
const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

const preview = await signa.watches.preview({
  query: {
    version: "v2",
    filters: { ownerId: "own_7pQmX3Lv" },
  },
  trial_window_days: 30,
});
console.log(`${preview.estimated_match_count} alerts in the last 30 days`);

Exact count

{
  "object": "watch_preview",
  "estimated_match_count": 17,
  "trial_window_days": 30,
  "request_id": "req_8mQ2vXpL"
}

{
  "object": "watch_preview",
  "estimated_match_count": 50000,
  "estimate_basis": "candidacy_upper_bound",
  "trial_window_days": 30,
  "request_id": "req_4nRvXq2T"
}

Related Endpoints

• Create Watch - turn a preview into a live watch
• Bulk Create Watches - create up to 100 watches at once
• Rate limits - request and concurrency limits