---
title: "Single NWS alert by identifier"
method: GET
path: "/api/v1/weather/nws/alert/{alert_id}"
tags: ["Environment"]
---

# Single NWS alert by identifier

`GET /api/v1/weather/nws/alert/{alert_id}`

Return a single hazard alert by its NWS identifier. Alert IDs are URN-formatted (for example `urn:oid:2.49.0.1.840.0.07a473b0d7a48517a9fc37bbd187447cab318920.001.2`) and must be URL-encoded in the path. The response is the flattened CAP payload with full description, instruction, affected zones, and polygon geometry if present. Issued alerts are effectively immutable once published; Sugra caches single-alert responses for an hour. Attribution: NOAA National Weather Service (api.weather.gov).

## Path parameters

- `alert_id` string, required — NWS alert URN (URL-encoded).

## Response `200`

Single NWS alert with full metadata.

- EnvelopeNwsAlertPayload
  - `data` NwsAlertPayload, required — Single-alert response (Feature shape flattened).
    - `id` string, nullable — URN alert identifier.
    - `sent` string, nullable — Time the alert was sent by the originator (ISO 8601).
    - `effective` string, nullable — Time the alert becomes effective (ISO 8601).
    - `onset` string, nullable — Expected onset of the hazard (ISO 8601).
    - `expires` string, nullable — Time the alert expires (ISO 8601).
    - `ends` string, nullable — Expected end of the hazard (ISO 8601).
    - `status` string, nullable — Alert status: Actual, Exercise, System, Test, Draft.
    - `message_type` string, nullable — Message type: Alert, Update, Cancel, Ack, Error.
    - `category` string, nullable — CAP category (e.g. Met, Safety, Geo, Rescue).
    - `severity` string, nullable — Severity: Extreme, Severe, Moderate, Minor, Unknown.
    - `certainty` string, nullable — Certainty: Observed, Likely, Possible, Unlikely, Unknown.
    - `urgency` string, nullable — Urgency: Immediate, Expected, Future, Past, Unknown.
    - `response` string, nullable — Recommended response: Shelter, Evacuate, Prepare, Execute, Avoid, Monitor, Assess, AllClear, None.
    - `event` string, nullable — Event label (e.g. `Tornado Warning`, `Frost Advisory`).
    - `sender` string, nullable — Sender address of the originating WFO or office.
    - `sender_name` string, nullable — Human-readable name of the issuing office (e.g. `NWS Upton NY`).
    - `headline` string, nullable — Short alert headline.
    - `description` string, nullable — Full alert description text.
    - `instruction` string, nullable — Recommended actions for the public.
    - `area_description` string, nullable — Plain-language geographic area covered (e.g. `Southern Westchester; Northeast Suffolk`).
    - `affected_zones` string[] — List of NWS zone IDs covered by this alert (extracted from the affectedZones URL list).
    - `geocode` object — UGC + SAME codes identifying the alert area at the county/zone level.
    - `parameters` object — Upstream-specific CAP parameters (AWIPS identifier, WMO identifier, NWSheadline, VTEC, etc.).
    - `geometry` object, nullable — GeoJSON geometry when the alert is polygon-based (e.g. short-fuse convective warnings). Null for zone-based alerts.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/revisions/4e2740743eb4/schema)