Lookup Alerts

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

POST /v1/alerts/lookup

Lookup Alerts

cURL

curl --request POST \
  --url https://api.signa.so/v1/alerts/lookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ids": [
    "<string>"
  ]
}
'

import requests

url = "https://api.signa.so/v1/alerts/lookup"

payload = { "ids": ["<string>"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ids: ['<string>']})
};

fetch('https://api.signa.so/v1/alerts/lookup', 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/lookup",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ids' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.signa.so/v1/alerts/lookup"

	payload := strings.NewReader("{\n  \"ids\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.signa.so/v1/alerts/lookup")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ids\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.signa.so/v1/alerts/lookup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ids\": [\n    \"<string>\"\n  ]\n}"

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
    }
  ],
  "request_id": "req_5nRvXq2T"
}

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.

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

Body Parameters

ids · string[] · required

1-100 alert IDs (alt_*).

Response

object · string

Always "list".

data · object[]

Array of Alert objects (see List Alerts for the shape). Order isn’t guaranteed to match ids.

request_id · string

Request identifier.

Errors

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

Code Examples

cURL

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"] }'

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"]);

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

Related Endpoints

• List Alerts - browse alerts with filters and pagination
• Retrieve Alert - fetch a single alert by ID