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

# Lookup Alerts

> Bulk-fetch alerts by ID, capped at 100 per call

## Overview

Polling pattern: when your webhook handler skips a delivery (endpoint offline, crash, hand-off
between workers), persist the alert IDs you've seen and reconcile by calling this endpoint to
confirm end-to-end delivery.

Malformed IDs, or IDs of the wrong type, fail the whole request with `400`, with each offending
entry called out by index (`ids[3]`). IDs that are well-formed but unknown, including IDs
belonging to another org, are silently dropped from the result rather than erroring, so any gap
between what you sent and what came back is real. `GET /v1/alerts/{id}` for a single unknown or
foreign ID still returns `404`.

Requires the `portfolios:manage` scope.

<Note>
  Lookup is a read-shaped operation, so the `Idempotency-Key` header is not required. Sending
  one, as in the example below, is always safe.
</Note>

## Body Parameters

<ParamField body="ids" type="string[]" required>
  1-100 alert IDs (`alt_*`).
</ParamField>

## Response

<ResponseField name="object" type="string">Always `"list"`.</ResponseField>
<ResponseField name="data" type="object[]">Array of `Alert` objects (see [List Alerts](/api-reference/monitoring/alerts/list) for the shape). Order isn't guaranteed to match `ids`.</ResponseField>
<ResponseField name="request_id" type="string">Request identifier.</ResponseField>

## Errors

| Status | `type`             | When                                                                               |
| ------ | ------------------ | ---------------------------------------------------------------------------------- |
| 400    | `validation_error` | `ids` is empty, has more than 100 entries, or contains a malformed / wrong-type ID |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.signa.so/v1/alerts/lookup" \
    -H "Authorization: Bearer sig_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: reconcile-alerts-2026-06-12" \
    -d '{ "ids": ["alt_4tYpL2Qn", "alt_3vXq7RmT"] }'
  ```

  ```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.lookup(["alt_4tYpL2Qn", "alt_3vXq7RmT"]);
  ```
</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
      }
    ],
    "request_id": "req_5nRvXq2T"
  }
  ```
</ResponseExample>

## Related Endpoints

* [List Alerts](/api-reference/monitoring/alerts/list) - browse alerts with filters and pagination
* [Retrieve Alert](/api-reference/monitoring/alerts/retrieve) - fetch a single alert by ID