Watch Diagnostics

curl --request GET \
  --url https://api.signa.so/v1/watches/{id}/diagnostics \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.signa.so/v1/watches/{id}/diagnostics', 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/{id}/diagnostics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.signa.so/v1/watches/{id}/diagnostics"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.signa.so/v1/watches/{id}/diagnostics")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "watch_id": "wat_8kLm2nPq",
  "trademark_id": "tm_9vXq3Rmt",
  "office_code": "US",
  "evaluated": true,
  "office_in_scope": true,
  "candidacy_passed": true,
  "trigger_event_type": "trademark.status_changed",
  "trigger_event_in_filter": true,
  "score_threshold": null,
  "min_match_tier": null,
  "similarity_applied": ["identical", "fuzzy", "embedded", "lookalike"],
  "min_tier": "similar",
  "alert_fired": true,
  "reason": "alert fired",
  "delivery_mode_effective": "per_alert",
  "lease_state": "released",
  "evaluation_epoch": 0,
  "replay_epoch_origin": null,
  "last_relevant_sync_run": {
    "id": "018f9b2e-0000-7000-8000-000000000001",
    "office_code": "US",
    "completed_at": "2026-07-06T04:12:00.000Z",
    "search_indexed_at": "2026-07-06T04:18:00.000Z"
  },
  "opensearch_score": 14.2,
  "alert_id": "alt_4tYpL2Qn",
  "opposition": {
    "must_act_by": "2026-09-04",
    "recomputed_close": "2026-09-04",
    "rule_id": "us_opposition",
    "rule_source": "15 U.S.C. § 1063(a)",
    "rule_version": "2026-05-06",
    "close_adjustment": "unchanged",
    "window_status": "open"
  },
  "data_window": {
    "trademark_changes_retention_days": 90,
    "deliveries_retention_days": 30,
    "alerts_retention_days": 90,
    "diagnostic_freshness_horizon_days": 90
  },
  "request_id": "req_2mR8vNkT"
}

{
  "watch_id": "wat_8kLm2nPq",
  "trademark_id": "tm_9vXq3Rmt",
  "office_code": "EM",
  "evaluated": true,
  "office_in_scope": true,
  "candidacy_passed": true,
  "trigger_event_type": "trademark.updated",
  "trigger_event_in_filter": false,
  "score_threshold": null,
  "min_match_tier": null,
  "similarity_applied": null,
  "min_tier": null,
  "alert_fired": false,
  "reason": "trigger event trademark.updated not in watch.trigger_events",
  "delivery_mode_effective": null,
  "lease_state": "released",
  "evaluation_epoch": 0,
  "replay_epoch_origin": null,
  "last_relevant_sync_run": {
    "id": "018f9b2e-0000-7000-8000-000000000002",
    "office_code": "EM",
    "completed_at": "2026-07-06T02:40:00.000Z",
    "search_indexed_at": "2026-07-06T02:45:00.000Z"
  },
  "opensearch_score": null,
  "alert_id": null,
  "opposition": null,
  "data_window": {
    "trademark_changes_retention_days": 90,
    "deliveries_retention_days": 30,
    "alerts_retention_days": 90,
    "diagnostic_freshness_horizon_days": 90
  },
  "request_id": "req_3vXq7RmT"
}

GET

watches

{id}

diagnostics

Watch Diagnostics

curl --request GET \
  --url https://api.signa.so/v1/watches/{id}/diagnostics \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.signa.so/v1/watches/{id}/diagnostics', 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/{id}/diagnostics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.signa.so/v1/watches/{id}/diagnostics"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.signa.so/v1/watches/{id}/diagnostics")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "watch_id": "wat_8kLm2nPq",
  "trademark_id": "tm_9vXq3Rmt",
  "office_code": "US",
  "evaluated": true,
  "office_in_scope": true,
  "candidacy_passed": true,
  "trigger_event_type": "trademark.status_changed",
  "trigger_event_in_filter": true,
  "score_threshold": null,
  "min_match_tier": null,
  "similarity_applied": ["identical", "fuzzy", "embedded", "lookalike"],
  "min_tier": "similar",
  "alert_fired": true,
  "reason": "alert fired",
  "delivery_mode_effective": "per_alert",
  "lease_state": "released",
  "evaluation_epoch": 0,
  "replay_epoch_origin": null,
  "last_relevant_sync_run": {
    "id": "018f9b2e-0000-7000-8000-000000000001",
    "office_code": "US",
    "completed_at": "2026-07-06T04:12:00.000Z",
    "search_indexed_at": "2026-07-06T04:18:00.000Z"
  },
  "opensearch_score": 14.2,
  "alert_id": "alt_4tYpL2Qn",
  "opposition": {
    "must_act_by": "2026-09-04",
    "recomputed_close": "2026-09-04",
    "rule_id": "us_opposition",
    "rule_source": "15 U.S.C. § 1063(a)",
    "rule_version": "2026-05-06",
    "close_adjustment": "unchanged",
    "window_status": "open"
  },
  "data_window": {
    "trademark_changes_retention_days": 90,
    "deliveries_retention_days": 30,
    "alerts_retention_days": 90,
    "diagnostic_freshness_horizon_days": 90
  },
  "request_id": "req_2mR8vNkT"
}

{
  "watch_id": "wat_8kLm2nPq",
  "trademark_id": "tm_9vXq3Rmt",
  "office_code": "EM",
  "evaluated": true,
  "office_in_scope": true,
  "candidacy_passed": true,
  "trigger_event_type": "trademark.updated",
  "trigger_event_in_filter": false,
  "score_threshold": null,
  "min_match_tier": null,
  "similarity_applied": null,
  "min_tier": null,
  "alert_fired": false,
  "reason": "trigger event trademark.updated not in watch.trigger_events",
  "delivery_mode_effective": null,
  "lease_state": "released",
  "evaluation_epoch": 0,
  "replay_epoch_origin": null,
  "last_relevant_sync_run": {
    "id": "018f9b2e-0000-7000-8000-000000000002",
    "office_code": "EM",
    "completed_at": "2026-07-06T02:40:00.000Z",
    "search_indexed_at": "2026-07-06T02:45:00.000Z"
  },
  "opensearch_score": null,
  "alert_id": null,
  "opposition": null,
  "data_window": {
    "trademark_changes_retention_days": 90,
    "deliveries_retention_days": 30,
    "alerts_retention_days": 90,
    "diagnostic_freshness_horizon_days": 90
  },
  "request_id": "req_3vXq7RmT"
}

Credits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.

Overview

Answers the question every monitoring customer eventually asks: “I expected an alert for this trademark. Why didn’t I get one?” Given a watch and a trademark, this endpoint walks through evaluation step by step and reports where it stopped, or confirms that an alert fired. It’s read-only: calling it never changes anything. Requires the portfolios:manage scope.

Path Parameters

string

required

Watch ID (wat_*).

Query Parameters

string

required

Trademark ID (tm_*) to check against this watch. A trademark ID from another org returns 404, and so does an ID that names no trademark (its error names the trademark, not the watch).

Response

string

Echoed watch ID (wat_*).

string

Echoed trademark ID (tm_*).

string

Uppercase ST.3 code of the office that issued the trademark (e.g. US, EM).

boolean

true if Signa evaluated this trademark against the watch within the current data window. false means either the change wasn’t recorded in time, or it has aged past the window. See reason.

boolean

true if this watch’s filters include the trademark’s office.

boolean

true if a change record for this trademark exists within the data window. A recorded change is a prerequisite for a match.

string | null

The lifecycle event associated with the match: trademark.created, trademark.updated, trademark.status_changed, trademark.retracted, or trademark.corrected.

boolean

true if trigger_event_type is included in the watch’s query.trigger_events filter. false explains a match that was silently dropped.

number | null

The engine score stored on the most recent alert for this (watch, trademark), the alert’s match.score. It scores the watch query and is not comparable to the 0 to 100 search relevance_score. null when no alert exists or the watch has no q. Informational only.

number | null

The watch’s stored query.score_threshold, surfaced only for legacy watches that still carry one. Inert: it no longer gates matching and is rejected on new writes. null when unset.

string[] | null

The similarity channels the watch query runs. null when the watch has no q, and for a watch created before 2026-09-29 that still uses the legacy query form.

'identical' | 'near_identical' | 'similar' | 'related' | null

The weakest match tier that can fire an alert. null for a legacy watch, which reports min_match_tier instead. See min_tier.

'exact' | 'normalized' | 'fuzzy' | 'phonetic' | null

Legacy watches only: the stored query.min_match_tier gate. null when the watch doesn’t gate by it (every legacy tier can fire) and for a v3 watch. See Watches created before 2026-09-29.

boolean

true if an alert exists for this (watch, trademark) pair.

string | null

Alert ID (alt_*) when one fired, otherwise null. Retrieve it with Get Alert, or cross-reference it against List webhook deliveries to confirm your endpoint received it.

string

Human-readable explanation for the outcome.

Value	Meaning
`alert fired`	An alert exists for this pair. `alert_id` is set.
`watch does not include office {code}`	This watch’s filters don’t cover the trademark’s office.
`trademark evaluated more than {N} days ago; provenance no longer available`	The change is older than the data window; Signa can no longer explain the outcome.
`trademark not in candidacy window for the most recent {office} sync`	No change was recorded recently enough for evaluation to consider this trademark.
`change not visible under provenance rules (no trademark.updated raised)`	Every field that changed is hidden by the public provenance rules (for example, a Signa-computed date moved), so no `trademark.updated` alert was raised.
`change predates the watch (the watch was created after this change)`	The change was recorded before the watch existed; watches are not applied to earlier changes.
`trigger event {type} not in watch.trigger_events`	The change happened, but its event type is excluded by this watch’s filter.
`watch is paused; paused watches evaluate no changes`	The watch is paused and has not evaluated this change.
`watch is paused: insufficient credits; top up credits to resume evaluation`	Signa paused the watch because the credit balance ran out.
`watch is disabled; disabled watches evaluate no changes`	The watch is disabled and has not evaluated this change.
`change not evaluated yet (the watch has not processed the sync run that carries it)`	The watch has not reached the data update that carries this change yet.
`would alert but rolled into digest`	The watch’s delivery mode resolved to a digest instead of an immediate alert.
`owner {id} was retired (suppressed) and matches no marks`	The watched owner record was retired as a duplicate and carries no marks; the stored ID was not changed. Watch the remaining owner record, or an entity, instead.
`mark did not match the watch query or filters`	The change was evaluated and its event type is wanted, but the mark does not match `q` or the filters. When a watched owner, attorney or firm was merged, the reason names it: `(owner own_A was merged into own_B; merge follow not enabled)`. Following merges ships disabled; once it is on, the note reads `the watch follows the survivor`.

'per_alert' | 'digest' | null

The delivery mode that applied. Today this is per_alert or null, since always_per_alert is the only mode a watch can be created with.

object | null

Computed opposition-window state for this trademark. null whenever no window can be cited: the trademark has no publication date, no opposition rule is modeled for its office and filing route, or the window could not be computed and there is no alert row to fall back on.

Show opposition

string | null

ISO date: last day to file. When an alert exists this is the value frozen onto that alert at emit time, not a fresh computation.

string | null

The engine’s close for this mark as computed right now. null when there is no alert (then must_act_by already is the recomputed close) and on the degraded path where the engine threw. When it differs from must_act_by, something moved after the alert was frozen: the office published a closure notice, a rule was corrected, or calendar coverage grew. Both dates are published rather than silently reconciled.

string | null

Stable, opaque slug of the opposition rule cited (e.g. us_opposition), and the join key to List Opposition Rules. Effectively always present when the opposition block is present, since an unmodeled office yields a null block rather than a block with a null rule_id. It is still emitted when the window itself could not be computed (rule_source and rule_version null), so a degraded block stays resolvable; the only path that yields null is that degraded path, when the rule lookup itself came back empty.

string | null

Human-readable name of the source the rule cites (e.g. "15 U.S.C. § 1063(a)"). For display, not identity.

string | null

Date the rule was last verified against its sources.

'moved' | 'unchanged' | 'not_checked' | 'month_end_overflow' | null

Whether the close date behind must_act_by was checked against the office’s holiday calendar, and whether that check moved it. not_checked means no calendar stands behind it: the close falls outside the calendar’s pinned coverage years, the office extends deadlines by dated notices that the engine does not model (today: Brazil, whose INPI Comunicados can move a deadline after the fact), the rule carries no calendar, or there is no publication date. A rollover only ever moves a close later, so a not_checked date is correct-or-early. null on the degraded path, where no window was produced at all (alongside a null rule_source / rule_version). It always describes the date this response serves, in this order: the marker frozen onto the alert (must_act_by_adjustment, the best evidence, computed for exactly that stored date); otherwise, if the frozen date disagrees with recomputed_close, not_checked, because the fresh marker describes a different date; otherwise the recomputed marker. Alert rows carry the frozen marker directly as deadline.must_act_by_adjustment on GET /v1/alerts and in the webhook body. Note the deliberate divergence when it reads not_checked: for the 20 days after that close, search buckets the mark as OPEN (a rollover could only have moved the close later) while POST /v1/oppositions/compute reports closed against the served, unverified date. Read the window as possibly still open and confirm with the office. See opposition windows.

'open' | 'closed' | 'not_started' | 'unknown' | null

Coarse window status.

object

Retention horizons for the data behind this response. See retention windows for how they interact with alerts and webhook deliveries.

Show data_window

integer

Days of change history available.

integer

Days of webhook delivery history available.

integer

Days alerts remain retrievable.

integer

The smallest of the windows above. Past this horizon, evaluated is false.

string

Request identifier.

Internal evaluation fields

These fields appear in the response but describe internal evaluation state. Safe to ignore when debugging alert delivery.

lease_state: internal evaluation state; safe to ignore.
evaluation_epoch: internal evaluation state; safe to ignore.
replay_epoch_origin: internal evaluation state; safe to ignore.
last_relevant_sync_run: internal evaluation state; safe to ignore.

Code Examples

curl "https://api.signa.so/v1/watches/wat_8kLm2nPq/diagnostics?trademark_id=tm_9vXq3Rmt" \
  -H "Authorization: Bearer sig_YOUR_KEY"

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

const trace = await signa.watches.diagnostics("wat_8kLm2nPq", {
  trademarkId: "tm_9vXq3Rmt",
});
console.log(trace.reason);

{
  "watch_id": "wat_8kLm2nPq",
  "trademark_id": "tm_9vXq3Rmt",
  "office_code": "US",
  "evaluated": true,
  "office_in_scope": true,
  "candidacy_passed": true,
  "trigger_event_type": "trademark.status_changed",
  "trigger_event_in_filter": true,
  "score_threshold": null,
  "min_match_tier": null,
  "similarity_applied": ["identical", "fuzzy", "embedded", "lookalike"],
  "min_tier": "similar",
  "alert_fired": true,
  "reason": "alert fired",
  "delivery_mode_effective": "per_alert",
  "lease_state": "released",
  "evaluation_epoch": 0,
  "replay_epoch_origin": null,
  "last_relevant_sync_run": {
    "id": "018f9b2e-0000-7000-8000-000000000001",
    "office_code": "US",
    "completed_at": "2026-07-06T04:12:00.000Z",
    "search_indexed_at": "2026-07-06T04:18:00.000Z"
  },
  "opensearch_score": 14.2,
  "alert_id": "alt_4tYpL2Qn",
  "opposition": {
    "must_act_by": "2026-09-04",
    "recomputed_close": "2026-09-04",
    "rule_id": "us_opposition",
    "rule_source": "15 U.S.C. § 1063(a)",
    "rule_version": "2026-05-06",
    "close_adjustment": "unchanged",
    "window_status": "open"
  },
  "data_window": {
    "trademark_changes_retention_days": 90,
    "deliveries_retention_days": 30,
    "alerts_retention_days": 90,
    "diagnostic_freshness_horizon_days": 90
  },
  "request_id": "req_2mR8vNkT"
}

{
  "watch_id": "wat_8kLm2nPq",
  "trademark_id": "tm_9vXq3Rmt",
  "office_code": "EM",
  "evaluated": true,
  "office_in_scope": true,
  "candidacy_passed": true,
  "trigger_event_type": "trademark.updated",
  "trigger_event_in_filter": false,
  "score_threshold": null,
  "min_match_tier": null,
  "similarity_applied": null,
  "min_tier": null,
  "alert_fired": false,
  "reason": "trigger event trademark.updated not in watch.trigger_events",
  "delivery_mode_effective": null,
  "lease_state": "released",
  "evaluation_epoch": 0,
  "replay_epoch_origin": null,
  "last_relevant_sync_run": {
    "id": "018f9b2e-0000-7000-8000-000000000002",
    "office_code": "EM",
    "completed_at": "2026-07-06T02:40:00.000Z",
    "search_indexed_at": "2026-07-06T02:45:00.000Z"
  },
  "opensearch_score": null,
  "alert_id": null,
  "opposition": null,
  "data_window": {
    "trademark_changes_retention_days": 90,
    "deliveries_retention_days": 30,
    "alerts_retention_days": 90,
    "diagnostic_freshness_horizon_days": 90
  },
  "request_id": "req_3vXq7RmT"
}

Retrieve Alert - fetch the alert this diagnosis references
List webhook deliveries - confirm your endpoint received the alert
Watches guide - watch types and the query DSL
Monitoring troubleshooting - retention windows and debugging walkthrough

Overview

Trademarks

Parties

Records

Intelligence

Filing & docketing

Monitoring

Analytics

Reference

Administration

SDK

Watch Diagnostics

Overview

Path Parameters

Query Parameters

Response

Code Examples

​Overview

​Path Parameters

​Query Parameters

​Response

​Code Examples

​Related Endpoints

Overview

Path Parameters

Query Parameters

Response

Code Examples

Related Endpoints