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

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

Signals appear in GET /v1/signals, GET /v1/signals/{id}, airport and carrier profiles, exposure results and webhook payloads, always in this shape.

Fields#

FieldTypeDescription
idstringStable 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.
typestringBroad category. See types and subtypes.
subtypestring | nullWhat kind of event within the type, e.g. ground_stop, earthquake, travel_advisory. The list grows with new sources; treat unknown values as valid.
providerstring | nullFor IT outages, the provider having the incident (aws, azure, gcp, cloudflare, microsoft_365, salesforce, ...). For FAA programs, faa. Otherwise usually null.
failure_layerstring | nullIT outages only: which layer failed, e.g. edge_cdn_dns, cloud_region, identity. The full list is at GET /v1/failure-layers.
failure_layer_labelstring | nullHuman label for failure_layer, e.g. "Edge, CDN and DNS".
titlestring | nullShort headline written from the source, at most about 140 characters. Not the source's full text.
severitystringminor, moderate, severe or extreme. See how severity is set.
statusstringactive or resolved. See lifecycle.
countriesstring[]ISO 3166-1 alpha-2 codes the signal affects. Can be empty, e.g. for a global cloud incident.
airportsstring[]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.
areasstring[]Area names as the source gives them (regions, warning zones, places). At most 25 in API responses.
locationobject | null{lat, lon} for signals with a point (earthquakes, storms, fires, FAA airports, news clusters). Null otherwise.
starts_atstring | nullWhen the event starts or started, if the source says. ISO 8601 UTC.
ends_atstring | nullWhen it is expected to end, if the source says. Set to the time of resolution when a signal resolves without one.
first_seen_atstringWhen DisruptAPI first saw it.
updated_atstringWhen it last changed materially (same moment version went up). Filter on this with since.
versionintegerStarts 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.urlstring | nullLink to the original report. Show it to users where you can.
source.attributionstring | nullThe credit line the source requires, e.g. "FAA NAS Status". See Data sources.
source.last_checked_atstring | nullWhen DisruptAPI last fetched this source successfully. Null if it never has, or for sources that are not polled.
source.stalebooleanTrue when the source has not been fetched successfully within its stale limit. The signal may have changed or ended without DisruptAPI seeing it.
detailsobjectSource-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_forecastobjectOnly on GET /v1/signals/{id}. See Forecasts.

TypeScript definitions for signals and the other response objects:

types.tsTypeScript
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.

TypeSubtypes (examples)Sources
aviationground_stop, ground_delay_program, airport_delay, airspace_flow_program, airport_closure, deicing, conflict_zone_airspace, volcanic_ash, rocket_launch, gnss_interferenceFAA NAS status, EASA conflict-zone bulletins, aviation SIGMETs, Launch Library 2, adsb.lol
weatherWarning types from the issuer, e.g. wind, snow_ice, thunderstorm (Meteoalarm awareness types) or winter_storm_warning (NWS); airport_weather; tropical_cycloneMeteoalarm, US NWS, Canada ECCC and other CAP feeds, METAR reports, NHC
natural_hazardearthquake, tropical_cyclone, flood, volcano, wildfire, drought, active_fire, and NWS hazard productsGDACS, USGS, NIFC, NASA FIRMS, US NWS
securitytravel_advisory, regional_advisory, civil_unrest, armed_conflict, curfew_or_emergencyTravel advisories from 6 governments; GDELT news events (news-derived)
laborstrikeGDELT news events (news-derived)
it_outagecloud_incident, provider_incident, saas_incident, saas_productivity_outageAWS, Azure, Google Cloud, Microsoft 365, Salesforce and Statuspage vendor status pages
internetcountry_connectivity_dropIODA
healthoutbreak, air quality productsCDC travel health notices, US NWS
infrastructureFrom the CAP issuerCAP 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:

SourceMapping
FAA NAS programsGround stops and airport closures severe; ground delay programs moderate; delays, airspace flow programs and de-icing minor.
Meteoalarm, CAP feedsThe issuer's CAP severity maps one to one (Minor, Moderate, Severe, Extreme). Meteoalarm green (minor) warnings are left out.
US NWSWarnings severe; hurricane, tornado, extreme wind, storm surge and tsunami warnings extreme; watches moderate; advisories minor.
GDACSRed alerts extreme, others severe.
USGS earthquakesM6.0 and above only: under M6.5 moderate, under M7.5 severe, else extreme; minor when no airport is nearby.
Travel advisoriesEach government's top level is extreme, the next severe; region-only advice is moderate or minor.
CDC noticesLevel 1 to 4 map to minor to extreme.
Statuspage vendors, Google CloudThe vendor's impact rating: minor or low minor, medium or degraded moderate, major or high severe, critical extreme.
AWS, Azure, Microsoft 365, Salesforcemoderate 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.

EventWhenStatus after
createdDisruptAPI sees the signal for the first time (version 1), or a resolved signal reappears in its source.active
escalatedSeverity went up, or more airports are affected.active
updatedAnother material change: severity down, title, countries, airports (fewer), end time, failure layer.active
resolvedThe source no longer lists it, or its ends_at has passed.resolved
  • Changes to details, areas or the location alone are saved but are not events: version and updated_at stay the same.
  • A signal whose ends_at passes 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 created again 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.stale flag 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: true means the signal may have changed or ended without DisruptAPI seeing it. It stays active until 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.