> ## 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 (offline,
crash, hand-off between workers), persist the `webhook-id` values you've
seen and reconcile by calling `POST /v1/alerts/lookup` to confirm
end-to-end delivery.

**ID handling:**

* **Malformed IDs or IDs of the wrong type** (anything that is not a
  well-formed `alt_*` ID) fail the **whole request** with `400
  validation_error`. The error detail lists each offending entry by index
  (`ids[3]`), so programming errors surface immediately instead of being
  silently swallowed.
* **Well-formed but unknown IDs** — and IDs that belong to another
  organization — are **silently dropped** from the result (no information
  disclosure). Any gap between the IDs you sent and the alerts you got back
  is real.
* `GET /v1/alerts/{id}` for an unknown/foreign ID returns `404`.

<Note>
  Lookup is a read-shaped operation, so the `Idempotency-Key` header is
  **accepted but no longer required**. Sending one (as in the example below)
  is always safe -- the header is format-validated and otherwise ignored.
</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 (order is not guaranteed to match input).</ResponseField>
<ResponseField name="request_id" type="string">Request identifier.</ResponseField>

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

  ```ts TypeScript theme={null}
  const alerts = await signa.alerts.lookup(['alt_01...', 'alt_02...']);
  ```
</RequestExample>