Signals
A signal is one disruption from one source, in one shape for every source. This page explains each field, the types and subtypes, how severity is set, how a signal changes over time and how to tell whether its source is still being read.
What does a signal look like?#
{
"id": "faa_ground_stop_SEA.k3j9x2m1qa",
"type": "aviation",
"subtype": "ground_stop",
"provider": "faa",
"failure_layer": null,
"failure_layer_label": null,
"title": "Ground Stop Program at SEA: low ceilings",
"severity": "severe",
"status": "active",
"countries": ["US"],
"airports": ["SEA"],
"areas": [],
"location": { "lat": 47.449, "lon": -122.309 },
"starts_at": null,
"ends_at": null,
"first_seen_at": "2026-11-18T06:52:10Z",
"updated_at": "2026-11-18T07:20:41Z",
"version": 2,
"source": {
"url": "https://nasstatus.faa.gov/",
"attribution": "FAA NAS Status",
"last_checked_at": "2026-11-18T07:21:02Z",
"stale": false
},
"details": { "reason": "low ceilings", "End_Time": "8:30 am PST" }
}{
"id": "sp_cloudflare_9x2kd81mzq3r.p2c7d0w5ha",
"type": "it_outage",
"subtype": "provider_incident",
"provider": "cloudflare",
"failure_layer": "edge_cdn_dns",
"failure_layer_label": "Edge, CDN and DNS",
"title": "Elevated errors for requests through our network",
"severity": "severe",
"status": "active",
"countries": [],
"airports": [],
"areas": [],
"location": null,
"starts_at": "2026-11-18T09:12:00Z",
"ends_at": null,
"first_seen_at": "2026-11-18T09:14:33Z",
"updated_at": "2026-11-18T09:40:05Z",
"version": 3,
"source": {
"url": "https://stspg.io/example",
"attribution": "Cloudflare status page",
"last_checked_at": "2026-11-18T09:41:00Z",
"stale": false
},
"details": {
"components": ["CDN/Cache", "DNS"],
"provider_status": "identified"
}
}Signals appear in GET /v1/signals, GET /v1/signals/{id}, airport and carrier profiles, exposure results and webhook payloads, always in this shape.
Fields#
| Field | Type | Description |
|---|---|---|
id | string | Stable id for this signal, as seen by your organisation: the internal id plus a 10-character suffix tied to your account, e.g. faa_ground_stop_SEA.k3j9x2m1qa. Use it with GET /v1/signals/{id}. Ids from another account return 404. |
type | string | Broad category. See types and subtypes. |
subtype | string | null | What kind of event within the type, e.g. ground_stop, earthquake, travel_advisory. The list grows with new sources; treat unknown values as valid. |
provider | string | null | For IT outages, the provider having the incident (aws, azure, gcp, cloudflare, microsoft_365, salesforce, ...). For FAA programs, faa. Otherwise usually null. |
failure_layer | string | null | IT outages only: which layer failed, e.g. edge_cdn_dns, cloud_region, identity. The full list is at GET /v1/failure-layers. |
failure_layer_label | string | null | Human label for failure_layer, e.g. "Edge, CDN and DNS". |
title | string | null | Short headline written from the source, at most about 140 characters. Not the source's full text. |
severity | string | minor, moderate, severe or extreme. See how severity is set. |
status | string | active or resolved. See lifecycle. |
countries | string[] | ISO 3166-1 alpha-2 codes the signal affects. Can be empty, e.g. for a global cloud incident. |
airports | string[] | IATA codes of airports the signal is placed at. For area warnings, the airports inside the warned areas where the area names could be matched. |
areas | string[] | Area names as the source gives them (regions, warning zones, places). At most 25 in API responses. |
location | object | null | {lat, lon} for signals with a point (earthquakes, storms, fires, FAA airports, news clusters). Null otherwise. |
starts_at | string | null | When the event starts or started, if the source says. ISO 8601 UTC. |
ends_at | string | null | When it is expected to end, if the source says. Set to the time of resolution when a signal resolves without one. |
first_seen_at | string | When DisruptAPI first saw it. |
updated_at | string | When it last changed materially (same moment version went up). Filter on this with since. |
version | integer | Starts at 1 and goes up by one on every created, escalated, updated or resolved event. id plus version identifies one state of a signal. |
source.url | string | null | Link to the original report. Show it to users where you can. |
source.attribution | string | null | The credit line the source requires, e.g. "FAA NAS Status". See Data sources. |
source.last_checked_at | string | null | When DisruptAPI last fetched this source successfully. Null if it never has, or for sources that are not polled. |
source.stale | boolean | True when the source has not been fetched successfully within its stale limit. The signal may have changed or ended without DisruptAPI seeing it. |
details | object | Source-specific facts, e.g. reason for FAA programs, components for status pages, placement for weather warnings, basis for news-derived and satellite signals. Keys differ by source and may be added; do not rely on a key being present. |
impact_forecast | object | Only on GET /v1/signals/{id}. See Forecasts. |
TypeScript definitions for signals and the other response objects:
type Severity = "minor" | "moderate" | "severe" | "extreme";
type RiskLevel = "none" | "low" | "elevated" | "high" | "severe";
type SignalType =
| "aviation" | "weather" | "natural_hazard" | "security" | "it_outage"
| "internet" | "health" | "labor" | "infrastructure";
interface Signal {
id: string; // per-account id: "<signal>.<tag>"
type: SignalType;
subtype: string | null;
provider: string | null;
failure_layer: string | null; // IT outages only
failure_layer_label: string | null;
title: string | null;
severity: Severity;
status: "active" | "resolved";
countries: string[]; // ISO 3166-1 alpha-2
airports: string[]; // IATA
areas: string[]; // at most 25
location: { lat: number; lon: number } | null;
starts_at: string | null; // ISO 8601 UTC
ends_at: string | null;
first_seen_at: string;
updated_at: string;
version: number;
source: {
url: string | null;
attribution: string | null;
last_checked_at: string | null;
stale: boolean;
};
details: Record<string, unknown>; // differs by source
impact_forecast?: Forecast; // GET /v1/signals/{id} only
}
interface ExposureMatch {
signal: Signal;
reasons: string[];
risk_contribution: RiskLevel;
forecast: {
outcomes: ForecastOutcome[];
recommended_actions: string[];
expected_duration_hours: ForecastDuration | null;
} | null;
grouped_signals?: number; // country-level weather groups only
areas_sample?: string[];
}
interface ExposureResult {
item_id: string | null;
trip_id: string | null; // same as item_id; kept for older clients
kind: "flight" | "trip" | "place" | "carrier" | "provider";
risk_level: RiskLevel;
match_count: number;
matches: ExposureMatch[]; // at most 20, highest risk first
warnings?: string[]; // e.g. unknown airport codes
watchlist_id?: string; // watchlist exposure only
}
interface ForecastOutcome {
outcome: string;
label: string;
probability: number;
interval: [number, number];
interval_level: number; // 0.8
k: number;
n: number;
analog_level: string;
low_confidence: boolean;
evidence: string;
base_rate: { probability: number; windows: number } | null;
lift: number | null;
above_base_rate: boolean | null;
}
interface ForecastDuration { p50: number | null; p90: number | null; n: number; analog_level: string }
interface Forecast {
basis: "analogs" | "insufficient_history";
failure_layer?: string | null;
failure_layer_label?: string | null;
analog_count: number;
analogs: unknown[];
outcomes: ForecastOutcome[];
expected_duration_hours: ForecastDuration | null;
carriers_at_elevated_risk: unknown[];
contrast?: string | null;
recommended_actions: string[];
notes: string[];
airport_base_rates?: Record<string, unknown>;
}
interface WebhookEvent {
id: string; // evt_..., new on every delivery attempt
type: `signal.${"created" | "escalated" | "updated" | "resolved"}`
| `exposure.${"created" | "escalated" | "updated" | "resolved"}`;
created_at: string;
data: Signal | { signal: Signal; exposed_items: ExposedItem[] };
}
interface ExposedItem {
item_id: string;
kind: string;
watchlist_id: string;
reasons: string[];
risk_contribution: RiskLevel;
}
interface ApiError {
error: { code: string; message: string; details?: { loc: string[]; msg: string; type: string }[] };
}Types and subtypes#
Filter by type with type= on GET /v1/signals (comma-separated) or types in webhook filters. Subtypes are open-ended: new sources add new ones, so do not reject values you do not know.
| Type | Subtypes (examples) | Sources |
|---|---|---|
aviation | ground_stop, ground_delay_program, airport_delay, airspace_flow_program, airport_closure, deicing, conflict_zone_airspace, volcanic_ash, rocket_launch, gnss_interference | FAA NAS status, EASA conflict-zone bulletins, aviation SIGMETs, Launch Library 2, adsb.lol |
weather | Warning types from the issuer, e.g. wind, snow_ice, thunderstorm (Meteoalarm awareness types) or winter_storm_warning (NWS); airport_weather; tropical_cyclone | Meteoalarm, US NWS, Canada ECCC and other CAP feeds, METAR reports, NHC |
natural_hazard | earthquake, tropical_cyclone, flood, volcano, wildfire, drought, active_fire, and NWS hazard products | GDACS, USGS, NIFC, NASA FIRMS, US NWS |
security | travel_advisory, regional_advisory, civil_unrest, armed_conflict, curfew_or_emergency | Travel advisories from 6 governments; GDELT news events (news-derived) |
labor | strike | GDELT news events (news-derived) |
it_outage | cloud_incident, provider_incident, saas_incident, saas_productivity_outage | AWS, Azure, Google Cloud, Microsoft 365, Salesforce and Statuspage vendor status pages |
internet | country_connectivity_drop | IODA |
health | outbreak, air quality products | CDC travel health notices, US NWS |
infrastructure | From the CAP issuer | CAP warning feeds with the "Infra" category |
How is severity set?#
Every signal has one of four severities, in increasing order: minor, moderate, severe, extreme. min_severity filters include the level you name and everything above it. Severity comes from the source's own scale where it has one; DisruptAPI does not raise or lower it based on your items. The mapping by source:
| Source | Mapping |
|---|---|
| FAA NAS programs | Ground stops and airport closures severe; ground delay programs moderate; delays, airspace flow programs and de-icing minor. |
| Meteoalarm, CAP feeds | The issuer's CAP severity maps one to one (Minor, Moderate, Severe, Extreme). Meteoalarm green (minor) warnings are left out. |
| US NWS | Warnings severe; hurricane, tornado, extreme wind, storm surge and tsunami warnings extreme; watches moderate; advisories minor. |
| GDACS | Red alerts extreme, others severe. |
| USGS earthquakes | M6.0 and above only: under M6.5 moderate, under M7.5 severe, else extreme; minor when no airport is nearby. |
| Travel advisories | Each government's top level is extreme, the next severe; region-only advice is moderate or minor. |
| CDC notices | Level 1 to 4 map to minor to extreme. |
| Statuspage vendors, Google Cloud | The vendor's impact rating: minor or low minor, medium or degraded moderate, major or high severe, critical extreme. |
| AWS, Azure, Microsoft 365, Salesforce | moderate or severe, from the scope the provider reports (for example several services or "unable to" wording raise it to severe). Azure incidents are severe. |
| News-derived (GDELT) | Set from how many independent outlets report it against the place's own baseline; never above severe. |
The risk level in exposure results is a different scale, worked out per item. See risk levels.
What is the signal lifecycle?#
DisruptAPI re-reads each source on its own schedule and compares what it finds with what it holds. Each change is one of four events. Webhooks fire on these events, and each event adds one to version and moves updated_at.
| Event | When | Status after |
|---|---|---|
created | DisruptAPI sees the signal for the first time (version 1), or a resolved signal reappears in its source. | active |
escalated | Severity went up, or more airports are affected. | active |
updated | Another material change: severity down, title, countries, airports (fewer), end time, failure layer. | active |
resolved | The source no longer lists it, or its ends_at has passed. | resolved |
- Changes to
details,areasor the location alone are saved but are not events:versionandupdated_atstay the same. - A signal whose
ends_atpasses is resolved within about a minute, and is never served as active after its end time. - A resolved signal that comes back in its source is
createdagain under the same id, with a higher version. - If a source that had 20 or more active signals suddenly returns none, they are kept active, since a broken feed is likelier than a quiet world. Their
source.staleflag tells you when the source stops answering.
How do versions work?#
version is a counter per signal. The pair (id, version) names one state of a signal, which makes it the right key for deduplication: if you have already processed faa_ground_stop_SEA.k3j9x2m1qa at version 3, a later copy at version 3 carries nothing new. Versions only go up. There is no endpoint for older versions of a signal.
Source attribution and freshness#
Every signal links to its source and names it in source.attribution. Many sources license their data on the condition that you credit them; if you show signals to your own users, show the attribution and the link. Data sources and coverage lists the licence terms.
source.last_checked_at and source.stale say how current the source is:
- Each source has a stale limit, by default four times its check interval. A source checked every 5 minutes is stale after 20 minutes without a successful fetch.
stale: truemeans the signal may have changed or ended without DisruptAPI seeing it. It staysactiveuntil its source says otherwise or its end time passes.- Backfilled history and retired feeds are never marked stale and have
last_checked_at: null.
GET /v1/sources gives the same freshness for every source at once. See handling stale sources.
Signal ids#
Ids are stable for the life of a signal and look like <source-derived id>.<10-character tag>. The tag is derived from your organisation, so the same signal has a different id in each account and an id copied from another account does not resolve. Treat ids as opaque strings; do not parse them.
Last updated 2026-11-18. Questions or a mistake on this page? Contact us.