> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Alerts

> List alerts for the calling org with cursor pagination

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

<ParamField query="limit" type="integer" default="20">Page size (1-100).</ParamField>
<ParamField query="cursor" type="string">Opaque cursor from the previous response.</ParamField>
<ParamField query="severity" type="string">Filter by `normal`, `high`, or `critical`.</ParamField>
<ParamField query="event_type" type="string">Filter by `trademark.created`, `trademark.updated`, `trademark.status_changed`, `trademark.retracted`, or `trademark.corrected`.</ParamField>
<ParamField query="epoch" type="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.</ParamField>

## Response

<ResponseField name="object" type="string">Always `"list"`.</ResponseField>

<ResponseField name="data" type="object[]">
  Array of `Alert` objects.

  <Expandable title="Alert">
    <ResponseField name="id" type="string">Alert ID (`alt_*`).</ResponseField>
    <ResponseField name="object" type="string">Always `"alert"`.</ResponseField>
    <ResponseField name="schema_version" type="string">Wire schema version, e.g. `"2026-06-01"`.</ResponseField>
    <ResponseField name="watch" type="object">Source watch summary: `id` (`wat_*`), `name`, `type`.</ResponseField>
    <ResponseField name="customer_reference" type="string | null">Passthrough value set on the watch's metadata; `null` if unset.</ResponseField>

    <ResponseField name="event" type="object">
      <Expandable title="event">
        <ResponseField name="type" type="string">One of the five event types above.</ResponseField>
        <ResponseField name="summary" type="string">Short human-readable description, e.g. `"Status changed: pending → registered"`.</ResponseField>
        <ResponseField name="diff" type="object[]">Field-level change entries: `path`, `op` (`set`, `unset`, or `changed`), and `from` / `to` for parent fields.</ResponseField>
        <ResponseField name="diff_truncated" type="boolean">Present and `true` when the diff was too large and some entries were dropped or clamped. Absent otherwise.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="match" type="object | null">
      Why the trademark matched, for watches that score matches. `null` for pure-filter watches.

      <Expandable title="match">
        <ResponseField name="reason" type="string | null">Match explanation.</ResponseField>
        <ResponseField name="score" type="number | null">Similarity score, when applicable.</ResponseField>
        <ResponseField name="score_basis" type="string | null">How the score was computed.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trademark" type="object">
      Snapshot of the trademark at the time of the alert.

      <Expandable title="trademark">
        <ResponseField name="id" type="string">Trademark ID (`tm_*`).</ResponseField>
        <ResponseField name="mark_text" type="string | null">Word mark.</ResponseField>
        <ResponseField name="mark_feature_type" type="string | null">Mark feature type.</ResponseField>
        <ResponseField name="office_code" type="string">Issuing office.</ResponseField>
        <ResponseField name="status" type="object">`primary` and `stage`.</ResponseField>
        <ResponseField name="filing_date" type="string | null">ISO date.</ResponseField>
        <ResponseField name="registration_date" type="string | null">ISO date.</ResponseField>
        <ResponseField name="nice_classes" type="integer[]">Nice classes on file at alert time.</ResponseField>
        <ResponseField name="owner_name" type="string | null">Owner name at alert time.</ResponseField>
        <ResponseField name="as_of" type="string | null">When the underlying change occurred.</ResponseField>
        <ResponseField name="links" type="object">`self`: link to the full trademark record.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="deadline" type="object">
      <Expandable title="deadline">
        <ResponseField name="severity" type="string">`normal`, `high`, or `critical`.</ResponseField>
        <ResponseField name="opposition_window_status" type="string | null">One of `open`, `closing_soon`, `critical`, `closed`.</ResponseField>
        <ResponseField name="must_act_by" type="string | null">Computed action deadline (ISO date).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="timestamps" type="object">`occurred_at`, `ingested_at` (omitted for older alerts with no linked change), `created_at`.</ResponseField>
    <ResponseField name="links" type="object">`trademark` and `watch`: links to the full resources.</ResponseField>
    <ResponseField name="evaluation_epoch" type="integer">The watch's evaluation revision this alert was emitted under.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">Whether more pages exist.</ResponseField>
<ResponseField name="pagination" type="object">Cursor envelope.</ResponseField>
<ResponseField name="request_id" type="string">Request identifier.</ResponseField>

## Errors

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

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/alerts?severity=critical&limit=50" \
    -H "Authorization: Bearer sig_YOUR_KEY"
  ```

  ```typescript TypeScript theme={null}
  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);
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## Related Endpoints

* [Retrieve Alert](/api-reference/monitoring/alerts/retrieve) - fetch a single alert
* [Lookup Alerts](/api-reference/monitoring/alerts/lookup) - bulk-fetch alerts by ID
* [List Alerts for Watch](/api-reference/monitoring/alerts/list-for-watch) - alerts scoped to one watch
* [Watch Diagnostics](/api-reference/monitoring/watches/diagnostics) - explain why a specific trademark did or didn't alert