List Alerts

List alerts for the calling org with cursor pagination

GET /v1/alerts

List Alerts

cURL

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"
      },
      "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 no PATCH or batch state operation. For polling clients, the recommended pattern is:

1. Pull pages (newest first) until you reach an id you’ve already processed.
2. Persist alert IDs in your own store as the system of record for “open work” or “acknowledged.”

Requires the portfolios:manage scope.

Query Parameters

limit · integer · default: "20"

Page size (1-100).

cursor · string

Opaque cursor from the previous response.

severity · string

Filter by normal, high, or critical.

event_type · string

Filter by trademark.created, trademark.updated, trademark.status_changed, trademark.retracted, or trademark.corrected.

epoch · 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

object · string

Always "list".

data · object[]

Array of Alert objects.

Show Alert

id · string

Alert ID (alt_*).

object · string

Always "alert".

schema_version · string

Wire schema version, e.g. "2026-06-01".

watch · object

Source watch summary: id (wat_*), name, type.

customer_reference · string | null

Passthrough value set on the watch’s metadata; null if unset.

event · object

Show event

type · string

One of the five event types above.

summary · string

Short human-readable description, e.g. "Status changed: pending → registered".

diff · object[]

Field-level change entries: path, op (set, unset, or changed), and from / to for parent fields.

diff_truncated · boolean

Present and true when the diff was too large and some entries were dropped or clamped. Absent otherwise.

match · object | null

Why the trademark matched, for watches that score matches. null for pure-filter watches.

Show match

reason · string | null

Match explanation.

score · number | null

Similarity score, when applicable.

score_basis · string | null

How the score was computed.

trademark · object

Snapshot of the trademark at the time of the alert.

Show trademark

id · string

Trademark ID (tm_*).

mark_text · string | null

Word mark.

mark_feature_type · string | null

Mark feature type.

office_code · string

Issuing office.

status · object

primary and stage.

filing_date · string | null

ISO date.

registration_date · string | null

ISO date.

nice_classes · integer[]

Nice classes on file at alert time.

owner_name · string | null

Owner name at alert time.

as_of · string | null

When the underlying change occurred.

links · object

self: link to the full trademark record.

deadline · object

Show deadline

severity · string

normal, high, or critical.

opposition_window_status · string | null

One of open, closing_soon, critical, closed.

must_act_by · string | null

Computed action deadline (ISO date).

timestamps · object

occurred_at, ingested_at (omitted for older alerts with no linked change), created_at.

links · object

trademark and watch: links to the full resources.

evaluation_epoch · integer

The watch’s evaluation revision this alert was emitted under.

has_more · boolean

Whether more pages exist.

pagination · object

Cursor envelope.

request_id · string

Request identifier.

Errors

Status	type	When
400	validation_error	Invalid severity, event_type, epoch, limit, or cursor

Code Examples

cURL

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"
      },
      "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