Watch Diagnostics

Check whether a watch fired, or should have fired, an alert for a specific trademark

GET /v1/watches/{id}/diagnostics

Watch Diagnostics

cURL

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

import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

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))

}

HttpResponse<String> response = Unirest.get("https://api.signa.so/v1/watches/{id}/diagnostics")
  .header("Authorization", "Bearer <token>")
  .asString();

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

Alert fired

{
  "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,
  "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": null,
  "alert_id": "alt_4tYpL2Qn",
  "opposition": {
    "must_act_by": "2026-09-04",
    "rule_source": "USPTO TMEP §1503.02",
    "rule_version": "2026.1",
    "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,
  "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"
}

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

id · string · required

Watch ID (wat_*).

Query Parameters

trademark_id · string · required

Trademark ID (tm_*) to check against this watch. A trademark ID from another org returns 404.

Response

watch_id · string

Echoed watch ID (wat_*).

trademark_id · string

Echoed trademark ID (tm_*).

office_code · string

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

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

office_in_scope · boolean

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

candidacy_passed · boolean

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

trigger_event_type · string | null

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

trigger_event_in_filter · boolean

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

opensearch_score · number | null

The persisted search relevance score (match_score) from the most recent alert for this (watch, trademark). null when no alert exists or the watch has no scored (q) clause. Informational only.

score_threshold · number | null

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

min_match_tier · 'exact' | 'normalized' | 'fuzzy' | 'phonetic' | null

The watch’s effective query.min_match_tier: which match attribution tiers can fire an alert. null when the watch doesn’t gate by tier (every tier can fire). See min_match_tier for tier meanings.

alert_fired · boolean

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

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

reason · 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.
trigger event {type} not in watch.trigger_events	The change happened, but its event type is excluded by this watch’s filter.
would alert but rolled into digest	The watch’s delivery mode resolved to a digest instead of an immediate alert.
no matching reason available	None of the above applied. Contact support if you see this.

delivery_mode_effective · '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.

opposition · object | null

Computed opposition-window state for this trademark. null when no rule applies.

Show opposition

must_act_by · string | null

ISO date: last day to file.

rule_source · string | null

Name of the rule that produced this deadline (e.g. "USPTO TMEP §1503.02").

rule_version · string | null

Rule version.

window_status · 'open' | 'closed' | 'not_started' | 'unknown' | null

Coarse window status.

data_window · object

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

Show data_window

trademark_changes_retention_days · integer

Days of change history available.

deliveries_retention_days · integer

Days of webhook delivery history available.

alerts_retention_days · integer

Days alerts remain retrievable.

diagnostic_freshness_horizon_days · integer

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

request_id · 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.
• opensearch_score: internal evaluation state; safe to ignore (currently always null).
• last_relevant_sync_run: internal evaluation state; safe to ignore.

Errors

Status	type	When
400	validation_error	trademark_id query parameter missing
403	forbidden	Caller lacks portfolios:manage
404	not_found	The watch or trademark doesn’t exist, belongs to another org, or the trademark is out of the watch’s scope with no alert on record. These cases return the same response so an ID guess can’t disclose another org’s data.

Code Examples

cURL

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);

Alert fired

{
  "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,
  "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": null,
  "alert_id": "alt_4tYpL2Qn",
  "opposition": {
    "must_act_by": "2026-09-04",
    "rule_source": "USPTO TMEP §1503.02",
    "rule_version": "2026.1",
    "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,
  "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"
}

Related Endpoints

• 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