Watchlists and exposure checks

An exposure check takes a list of items (flights, trips, places such as hotels, airlines and technology providers) and returns the active signals that touch each one, the reasons and a risk level. A watchlist saves items so they are checked against every new signal and can trigger webhooks.

Which item kinds are there?#

There are five kinds. Hotels, venues, offices and traveller locations are all place items.

KindUse it forMatched on
flightOne booked flightOrigin and destination airports and their countries, the carrier (for IT outages), departure to arrival time
tripA multi-leg itinerary or round tripEvery airport and carrier on every leg, from first departure to return_at or last arrival
placeA hotel, venue, office, airport or countryThe airport, or the point with its radius and up to 5 airports inside it, the country, the stay dates
carrierAn airline you sell or depend onIT outages that put the airline at medium or high risk
providerA cloud or SaaS provider your systems useIT outages reported by that provider, optionally in one failure layer
Item examples
{
  "id": "BKG-7QX2LM",
  "kind": "flight",
  "carrier": "AS",
  "origin": "SEA",
  "destination": "HNL",
  "depart_at": "2026-11-21T08:00:00Z",
  "arrive_at": "2026-11-21T14:05:00Z"
}

Item fields#

Send the fields that apply to the kind. Unknown airport codes do not fail the request; they come back in warnings.

FieldTypeDescription
idstringYour own reference, at most 100 characters. Optional for exposure checks; required in watchlists, where it is the key for updates and removal.
kindstringflight, trip, place, carrier or provider. Leave it out and it is inferred.
labelstringA name for humans, at most 200 characters. Used in match reasons, e.g. "12 km from Hotel Alcudia".
carrierstringIATA airline code (flight, trip, carrier).
carriersstring[]Several airline codes, at most 50.
originstringIATA airport code (flight, trip).
destinationstringIATA airport code (flight, trip).
viastring[]Connection airports, at most 50 (trip).
legsobject[]Up to 20 legs, each with carrier, origin, destination, depart_at, arrive_at (trip).
depart_atstringISO 8601 departure time (flight, trip).
arrive_atstringISO 8601 arrival time, on a flight or a leg.
return_atstringEnd of a round trip (trip).
airportstringIATA airport code (place).
latnumberLatitude, -90 to 90 (place). Send with lon.
lonnumberLongitude, -180 to 180 (place).
radius_kmnumberReach around lat/lon, above 0 and at most 500. Default: 75.
countrystringISO 3166-1 alpha-2 code (place).
countriesstring[]More country codes to match on, at most 50 (any kind).
starts_atstringStart of a stay or period of interest (place, carrier).
ends_atstringEnd of a stay or period of interest (place, carrier).
providerstringTechnology provider, e.g. aws, azure, gcp, cloudflare, microsoft_365, salesforce, akamai, github, twilio (provider). GET /v1/providers lists the watched providers. At most 60 characters.
failure_layerstringOnly match incidents in this layer, e.g. edge_cdn_dns (provider).
expires_atstringWatchlists only: stop matching the item after this UTC time. Overrides the automatic expiry.
any other fieldanyYour own metadata is kept with watchlist items and returned by GET /v1/watchlists/{id}. Each item can be at most 4 KB as JSON.

How is the kind inferred?#

If you leave out kind, the first rule that applies decides it:

IfKind
kind is set to a valid valuethat kind
legs is presenttrip
provider is presentprovider
origin or destination is presenttrip if via or return_at is also present, else flight
lat, airport or country is presentplace
carrier is presentcarrier
none of the abovetrip with nothing to match on, so it never matches

Setting kind explicitly avoids surprises, for example a flight with a return_at being treated as a trip.

How does matching work?#

Each item is reduced to a footprint: airports, countries, carriers, providers, points with a radius, and a time window. Every active signal at or above min_severity (default moderate) is then compared with it. A signal matches when at least one of these is true, and each one adds a line to reasons:

Airport
The signal lists one of the item's airports. Reason: "affects SEA". For weather warnings placed by area, the warned area is named.
Distance
For places with lat/lon: the signal's location is within the item's radius plus the signal's own radius, if it has one. Reason: "12 km from Hotel Alcudia".
Country
For weather, security, internet and health signals only, and only when no airport or distance match was found: the signal covers one of the item's countries. A flight's countries are those of its airports; a place with coordinates takes the country of its nearest airport unless you send one. Reason: "covers PE".
Carrier
For IT outages: the item's airline is at medium or high risk from the incident, based on what its public systems run on and past events. Reason: "AS at high risk: ...".
Provider
For IT outages: the provider reporting the incident is the item's provider, or part of its family (for example gcp covers Google Cloud). If the item has a failure_layer, the incident must be in that layer. Reason: "you depend on cloudflare, which reports this incident".

Time windows#

When both sides have times, they must overlap. A signal that starts after the item ends is skipped, except travel advisories and other security signals, which apply whenever they are active. A signal that ended before the item starts is skipped. Items or signals without times match at any time.

Country-level weather groups#

Weather warnings whose areas could not be matched to airports are grouped per country and warning type into one match, so an item in Spain does not get forty separate wind warnings. The group carries grouped_signals (how many), areas_sample (up to 15 area names), the worst warning as signal, and a reason that says it was placed at country level. When every area of a warning was recognised and none holds the item's airports, it does not match by country at all.

How is the risk level worked out?#

Each match has a risk_contribution, and the item's risk_level is the highest of them, or none without matches. A match starts from the signal's severity:

Signal severityRisk contribution
minorlow
moderateelevated
severehigh
extremesevere
  • Weather that matches only by country is one level lower (never below low).
  • An IT outage that matches through your provider, or through a carrier at high risk, is one level higher (at most severe).

Matches are sorted by risk, highest first, and at most 20 are returned per item; match_count is the full number. IT outage matches include a short forecast (top outcomes, recommended actions, expected duration).

Run an exposure check#

POST /v1/exposure/check takes up to 500 items. Results come back in the order you sent them, one per item.

Request
curl -X POST "https://app.disruptapi.com/v1/exposure/check" \
  -H "Authorization: Bearer $DISRUPT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "id": "TRIP-4471",
      "kind": "trip",
      "legs": [
        {
          "carrier": "TP",
          "origin": "FRA",
          "destination": "LIS",
          "depart_at": "2026-12-03T06:40:00Z"
        }
      ]
    },
    { "id": "hub-SEA", "kind": "place", "airport": "SEA" }
  ],
  "min_severity": "moderate"
}'
Response (shortened)JSON
{
  "data": [
    {
      "item_id": "TRIP-4471",
      "trip_id": "TRIP-4471",
      "kind": "trip",
      "risk_level": "none",
      "match_count": 0,
      "matches": []
    },
    {
      "item_id": "hub-SEA",
      "trip_id": "hub-SEA",
      "kind": "place",
      "risk_level": "high",
      "match_count": 1,
      "matches": [
        {
          "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": {}
          },
          "reasons": ["affects SEA"],
          "risk_contribution": "high",
          "forecast": null
        }
      ]
    }
  ]
}

trip_id repeats item_id for older clients. The request field trips is still accepted as an older name for items.

Watchlists#

A watchlist is a named, saved set of items. Every item needs an id, and ids are unique within a watchlist: posting an item with an existing id replaces it, so you can sync bookings by sending them whenever they change.

  • POST /v1/watchlists creates one, optionally with up to 1,000 items. If any item is invalid, nothing is created.
  • POST /v1/watchlists/{id}/items adds or replaces 1 to 1,000 items per call. The response says how many were stored and how many were new.
  • DELETE /v1/watchlists/{id}/items/{item_id} removes one item.
  • GET /v1/watchlists/{id}/exposure returns only the items that are exposed right now, each with its watchlist_id.
  • A webhook with "watchlists": ["*"] (or a list of watchlist ids) fires when a signal touches any of their items. See Webhooks.
Add or update items
curl -X POST "https://app.disruptapi.com/v1/watchlists/wl_3f9a1c2b7d4e5f60/items" \
  -H "Authorization: Bearer $DISRUPT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "id": "BKG-7QX2LM",
      "kind": "flight",
      "carrier": "AS",
      "origin": "SEA",
      "destination": "HNL",
      "depart_at": "2026-11-22T08:00:00Z"
    }
  ]
}'
ResponseJSON
{ "data": { "stored": 1, "new": 0 } }

How many items can I watch?#

The limit counts live items across all your watchlists: Sandbox 5, Starter 2,500, Pro 50,000, Enterprise unlimited. Going over it fails the whole call with 400 invalid_items; updating existing items does not count as new. GET /v1/watchlists returns limits.watch_items and limits.used.

When do watchlist items expire?#

Expired items stop matching, are left out of listings and no longer count towards your limit. Re-sending the same id brings an item back with new dates.

ItemExpires
expires_at is setAt expires_at.
flight or tripOne day after it ends: return_at, else the latest arrive_at or depart_at.
place or carrier with ends_at (or only starts_at)One day after ends_at, or one day after starts_at if that is all it has.
anything without times (most places, carriers, providers)Never. It stays until you remove it.

Limits#

LimitValue
Items per exposure check500
Items per watchlist create or add call1,000
Item size4 KB as JSON
legs per item20
carriers, via, countries entries50 each
radius_kmabove 0, at most 500 (default 75)
Watchlist name / description1 to 100 / at most 500 characters
Items returned by GET /v1/watchlists/{id}limit, 1 to 1,000 (default 100), newest first

Last updated 2026-11-18. Questions or a mistake on this page? Contact us.