List Alerts
curl --request GET \
--url https://api.signa.so/v1/alerts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.signa.so/v1/alerts"
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/alerts', 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/alerts",
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/alerts"
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/alerts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.signa.so/v1/alerts")
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{
"object": "list",
"data": [
{
"id": "alt_4tYpL2Qn",
"object": "alert",
"schema_version": "2026-06-01",
"watch": { "id": "wat_8kLm2nPq", "name": "Nike owner watch", "type": "owner" },
"customer_reference": null,
"event": {
"type": "trademark.status_changed",
"summary": "Status stage changed: published → registered",
"diff": [
{ "path": "status_stage", "op": "changed", "from": "published", "to": "registered" }
]
},
"match": null,
"trademark": {
"id": "tm_9vXq3Rmt",
"mark_text": "NIKE",
"mark_feature_type": "word",
"office_code": "US",
"status": { "primary": "active", "stage": "registered" },
"filing_date": "2024-02-01",
"registration_date": "2026-07-01",
"nice_classes": [25, 28],
"owner_name": "Nike, Inc.",
"as_of": "2026-07-05T09:10:00.000Z",
"links": { "self": "/v1/trademarks/tm_9vXq3Rmt" }
},
"deadline": {
"severity": "high",
"opposition_window_status": "open",
"must_act_by": "2026-09-04",
"must_act_by_adjustment": "unchanged"
},
"timestamps": {
"occurred_at": "2026-07-05T09:10:00.000Z",
"ingested_at": "2026-07-05T09:12:00.000Z",
"created_at": "2026-07-05T09:12:30.000Z"
},
"links": { "trademark": "/v1/trademarks/tm_9vXq3Rmt", "watch": "/v1/watches/wat_8kLm2nPq" },
"evaluation_epoch": 0
}
],
"has_more": false,
"pagination": { "cursor": null },
"request_id": "req_2mR8vNkT"
}
Alerts
List Alerts
List alerts for the calling org with cursor pagination
GET
/
v1
/
alerts
List Alerts
curl --request GET \
--url https://api.signa.so/v1/alerts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.signa.so/v1/alerts"
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/alerts', 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/alerts",
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/alerts"
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/alerts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.signa.so/v1/alerts")
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{
"object": "list",
"data": [
{
"id": "alt_4tYpL2Qn",
"object": "alert",
"schema_version": "2026-06-01",
"watch": { "id": "wat_8kLm2nPq", "name": "Nike owner watch", "type": "owner" },
"customer_reference": null,
"event": {
"type": "trademark.status_changed",
"summary": "Status stage changed: published → registered",
"diff": [
{ "path": "status_stage", "op": "changed", "from": "published", "to": "registered" }
]
},
"match": null,
"trademark": {
"id": "tm_9vXq3Rmt",
"mark_text": "NIKE",
"mark_feature_type": "word",
"office_code": "US",
"status": { "primary": "active", "stage": "registered" },
"filing_date": "2024-02-01",
"registration_date": "2026-07-01",
"nice_classes": [25, 28],
"owner_name": "Nike, Inc.",
"as_of": "2026-07-05T09:10:00.000Z",
"links": { "self": "/v1/trademarks/tm_9vXq3Rmt" }
},
"deadline": {
"severity": "high",
"opposition_window_status": "open",
"must_act_by": "2026-09-04",
"must_act_by_adjustment": "unchanged"
},
"timestamps": {
"occurred_at": "2026-07-05T09:10:00.000Z",
"ingested_at": "2026-07-05T09:12:00.000Z",
"created_at": "2026-07-05T09:12:30.000Z"
},
"links": { "trademark": "/v1/trademarks/tm_9vXq3Rmt", "watch": "/v1/watches/wat_8kLm2nPq" },
"evaluation_epoch": 0
}
],
"has_more": false,
"pagination": { "cursor": null },
"request_id": "req_2mR8vNkT"
}
Overview
Returns alerts produced by any of the org’s watches. Alerts are immutable; there’s noPATCH or
batch state operation. For polling clients, the recommended pattern is:
- Pull pages (newest first) until you reach an
idyou’ve already processed. - Persist alert IDs in your own store as the system of record for “open work” or “acknowledged.”
portfolios:manage scope.
Query Parameters
integer
default:"20"
Page size (1-100).
string
Opaque cursor from the previous response.
string
Filter by
normal, high, or critical.string
Filter by
trademark.created, trademark.updated, trademark.status_changed, trademark.retracted, or trademark.corrected.string
default:"all"
all (default) returns alerts from every evaluation revision of a watch; current returns only alerts emitted under each watch’s current query.Response
string
Always
"list".object[]
Array of
Alert objects.Show Alert
Show Alert
string
Alert ID (
alt_*).string
Always
"alert".string
Wire schema version, e.g.
"2026-06-01".object
Source watch summary:
id (wat_*), name, type.string | null
Passthrough value set on the watch’s metadata;
null if unset.object
Show event
Show event
string
One of the five event types above.
string
Short human-readable description, e.g.
"Status changed: pending → registered".object[]
Field-level change entries:
path, op (set, unset, or changed), and from / to for parent fields. path is a public trademark field name — status, mark_text, publication_date, ir_number, or a changed child collection (owners, classifications, media, …). Status is flattened: status.primary is status, the rest are status_<key>. Fields Signa does not publish are omitted rather than renamed, so every path resolves against the trademark resource. See Webhooks: diff field names.boolean
Present and
true when the diff was too large and some entries were dropped or clamped. Absent otherwise.object | null
object
Snapshot of the trademark at the time of the alert.
Show trademark
Show trademark
string
Trademark ID (
tm_*).string | null
Word mark.
string | null
Mark feature type.
string
Issuing office.
object
primary and stage.string | null
ISO date.
string | null
ISO date.
integer[]
Nice classes on file at alert time.
string | null
Owner name at alert time.
string | null
When the underlying change occurred.
object
self: link to the full trademark record.object
Show deadline
Show deadline
string
normal, high, or critical.string | null
One of
open, closing_soon, critical, closed.string | null
Computed action deadline (ISO date). Frozen when the alert was emitted, not recomputed on read.
string | null
Whether a holiday calendar stood behind
must_act_by when it was frozen onto this alert: moved, unchanged, not_checked or month_end_overflow. not_checked means no pinned closure list verified the date: the close fell outside the office calendar’s pinned coverage years (the deterministic roll over weekends and the fixed holidays the calendar computes from the law may still have moved it), or the rule ships without a calendar. The true close can only be the same or later, so a not_checked date is correct-or-early and must not be diarised as final. null on alerts emitted before 23 September 2026 and on alerts with no opposition window; read null as “no marker was recorded”, never as “verified”. See opposition windows.object
occurred_at, ingested_at (omitted for older alerts with no linked change), created_at.object
trademark and watch: links to the full resources.integer
The watch’s evaluation revision this alert was emitted under.
boolean
Whether more pages exist.
object
Cursor envelope.
string
Request identifier.
Errors
| Status | type | When |
|---|---|---|
| 400 | validation_error | Invalid severity, event_type, epoch, limit, or cursor |
Code Examples
curl "https://api.signa.so/v1/alerts?severity=critical&limit=50" \
-H "Authorization: Bearer sig_YOUR_KEY"
import { Signa } from "@signa-so/sdk";
const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });
const alerts = await signa.alerts.list({ severity: "critical", limit: 50 });
for await (const a of alerts) {
if (a.deadline.severity === "critical") console.log("escalate:", a.id);
}
{
"object": "list",
"data": [
{
"id": "alt_4tYpL2Qn",
"object": "alert",
"schema_version": "2026-06-01",
"watch": { "id": "wat_8kLm2nPq", "name": "Nike owner watch", "type": "owner" },
"customer_reference": null,
"event": {
"type": "trademark.status_changed",
"summary": "Status stage changed: published → registered",
"diff": [
{ "path": "status_stage", "op": "changed", "from": "published", "to": "registered" }
]
},
"match": null,
"trademark": {
"id": "tm_9vXq3Rmt",
"mark_text": "NIKE",
"mark_feature_type": "word",
"office_code": "US",
"status": { "primary": "active", "stage": "registered" },
"filing_date": "2024-02-01",
"registration_date": "2026-07-01",
"nice_classes": [25, 28],
"owner_name": "Nike, Inc.",
"as_of": "2026-07-05T09:10:00.000Z",
"links": { "self": "/v1/trademarks/tm_9vXq3Rmt" }
},
"deadline": {
"severity": "high",
"opposition_window_status": "open",
"must_act_by": "2026-09-04",
"must_act_by_adjustment": "unchanged"
},
"timestamps": {
"occurred_at": "2026-07-05T09:10:00.000Z",
"ingested_at": "2026-07-05T09:12:00.000Z",
"created_at": "2026-07-05T09:12:30.000Z"
},
"links": { "trademark": "/v1/trademarks/tm_9vXq3Rmt", "watch": "/v1/watches/wat_8kLm2nPq" },
"evaluation_epoch": 0
}
],
"has_more": false,
"pagination": { "cursor": null },
"request_id": "req_2mR8vNkT"
}
Related Endpoints
- Retrieve Alert - fetch a single alert
- Lookup Alerts - bulk-fetch alerts by ID
- List Alerts for Watch - alerts scoped to one watch
- Watch Diagnostics - explain why a specific trademark did or didn’t alert