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.
| Kind | Use it for | Matched on |
|---|---|---|
flight | One booked flight | Origin and destination airports and their countries, the carrier (for IT outages), departure to arrival time |
trip | A multi-leg itinerary or round trip | Every airport and carrier on every leg, from first departure to return_at or last arrival |
place | A hotel, venue, office, airport or country | The airport, or the point with its radius and up to 5 airports inside it, the country, the stay dates |
carrier | An airline you sell or depend on | IT outages that put the airline at medium or high risk |
provider | A cloud or SaaS provider your systems use | IT outages reported by that provider, optionally in one failure layer |
{
"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"
}{
"id": "TRIP-4471",
"kind": "trip",
"label": "Lisbon incentive group",
"legs": [
{
"carrier": "TP",
"origin": "FRA",
"destination": "LIS",
"depart_at": "2026-12-03T06:40:00Z",
"arrive_at": "2026-12-03T09:15:00Z"
},
{
"carrier": "TP",
"origin": "LIS",
"destination": "FRA",
"depart_at": "2026-12-07T18:10:00Z",
"arrive_at": "2026-12-07T22:30:00Z"
}
]
}{
"id": "PNR-ZX81QK",
"kind": "trip",
"carriers": ["LH", "SQ"],
"origin": "MUC",
"destination": "SYD",
"via": ["SIN"],
"depart_at": "2026-12-10T21:00:00Z",
"return_at": "2026-12-28T09:00:00Z"
}{
"id": "HTL-ALCUDIA",
"kind": "place",
"label": "Hotel Alcudia",
"lat": 39.85,
"lon": 3.12,
"radius_km": 40,
"starts_at": "2026-12-03T14:00:00Z",
"ends_at": "2026-12-07T11:00:00Z",
"booking_ref": "H-99812"
}{ "id": "hub-FRA", "kind": "place", "airport": "FRA" }{
"id": "traveller-881",
"kind": "place",
"country": "PE",
"starts_at": "2026-11-20T00:00:00Z",
"ends_at": "2026-12-02T00:00:00Z"
}{ "id": "airline-AS", "kind": "carrier", "carrier": "AS" }{
"id": "checkout-cdn",
"kind": "provider",
"provider": "cloudflare",
"failure_layer": "edge_cdn_dns"
}Item fields#
Send the fields that apply to the kind. Unknown airport codes do not fail the request; they come back in warnings.
| Field | Type | Description |
|---|---|---|
id | string | Your own reference, at most 100 characters. Optional for exposure checks; required in watchlists, where it is the key for updates and removal. |
kind | string | flight, trip, place, carrier or provider. Leave it out and it is inferred. |
label | string | A name for humans, at most 200 characters. Used in match reasons, e.g. "12 km from Hotel Alcudia". |
carrier | string | IATA airline code (flight, trip, carrier). |
carriers | string[] | Several airline codes, at most 50. |
origin | string | IATA airport code (flight, trip). |
destination | string | IATA airport code (flight, trip). |
via | string[] | Connection airports, at most 50 (trip). |
legs | object[] | Up to 20 legs, each with carrier, origin, destination, depart_at, arrive_at (trip). |
depart_at | string | ISO 8601 departure time (flight, trip). |
arrive_at | string | ISO 8601 arrival time, on a flight or a leg. |
return_at | string | End of a round trip (trip). |
airport | string | IATA airport code (place). |
lat | number | Latitude, -90 to 90 (place). Send with lon. |
lon | number | Longitude, -180 to 180 (place). |
radius_km | number | Reach around lat/lon, above 0 and at most 500. Default: 75. |
country | string | ISO 3166-1 alpha-2 code (place). |
countries | string[] | More country codes to match on, at most 50 (any kind). |
starts_at | string | Start of a stay or period of interest (place, carrier). |
ends_at | string | End of a stay or period of interest (place, carrier). |
provider | string | Technology 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_layer | string | Only match incidents in this layer, e.g. edge_cdn_dns (provider). |
expires_at | string | Watchlists only: stop matching the item after this UTC time. Overrides the automatic expiry. |
any other field | any | Your 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:
| If | Kind |
|---|---|
kind is set to a valid value | that kind |
legs is present | trip |
provider is present | provider |
origin or destination is present | trip if via or return_at is also present, else flight |
lat, airport or country is present | place |
carrier is present | carrier |
| none of the above | trip 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
gcpcovers Google Cloud). If the item has afailure_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 severity | Risk contribution |
|---|---|
minor | low |
moderate | elevated |
severe | high |
extreme | severe |
- 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.
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"
}'// Node.js 18+ (built-in fetch), saved as an .mjs file
const res = await fetch("https://app.disruptapi.com/v1/exposure/check", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DISRUPT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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",
}),
signal: AbortSignal.timeout(30_000),
});
const json = await res.json();
if (!res.ok) {
throw new Error(`${res.status} ${json.error.code}: ${json.error.message}`);
}
console.log(JSON.stringify(json.data, null, 2));import os
import requests
resp = requests.post(
"https://app.disruptapi.com/v1/exposure/check",
headers={"Authorization": f"Bearer {os.environ['DISRUPT_KEY']}"},
json={
"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",
},
timeout=30,
)
if not resp.ok:
err = resp.json()["error"]
raise SystemExit(f"{resp.status_code} {err['code']}: {err['message']}")
print(resp.json()["data"])import os
import httpx
with httpx.Client(
base_url="https://app.disruptapi.com",
headers={"Authorization": f"Bearer {os.environ['DISRUPT_KEY']}"},
timeout=30,
) as client:
resp = client.post(
"/v1/exposure/check",
json={
"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",
},
)
if resp.is_error:
err = resp.json()["error"]
raise SystemExit(f"{resp.status_code} {err['code']}: {err['message']}")
print(resp.json()["data"])package main
import (
"bytes"
"fmt"
"io"
"log"
"net/http"
"os"
"time"
)
func main() {
body := []byte(`{
"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"
}`)
req, err := http.NewRequest(http.MethodPost, "https://app.disruptapi.com/v1/exposure/check", bytes.NewReader(body))
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("DISRUPT_KEY"))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 30 * time.Second}
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
out, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.StatusCode, string(out))
}require "json"
require "net/http"
require "uri"
uri = URI("https://app.disruptapi.com/v1/exposure/check")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("DISRUPT_KEY")}"
req["Content-Type"] = "application/json"
req.body = <<~JSON
{
"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"
}
JSON
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
http.request(req)
end
json = JSON.parse(res.body)
abort "#{res.code} #{json["error"]["code"]}: #{json["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts JSON.pretty_generate(json["data"])<?php
$payload = <<<'JSON'
{
"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"
}
JSON;
$ch = curl_init("https://app.disruptapi.com/v1/exposure/check");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("DISRUPT_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $payload,
]);
$raw = curl_exec($ch);
if ($raw === false) {
exit("request failed: " . curl_error($ch) . PHP_EOL);
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($raw, true);
if ($status >= 400) {
exit("{$status} {$json['error']['code']}: {$json['error']['message']}" . PHP_EOL);
}
print_r($json["data"]);// Java 17+. Run with: java Main.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
public class Main {
public static void main(String[] args) throws Exception {
String body = """
{
"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"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://app.disruptapi.com/v1/exposure/check"))
.timeout(Duration.ofSeconds(30))
.header("Authorization", "Bearer " + System.getenv("DISRUPT_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}// .NET 7+ console app (top-level statements, C# 11 raw strings)
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("DISRUPT_KEY"));
var body = """
{
"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"
}
""";
using var content = new StringContent(body, Encoding.UTF8, "application/json");
using var response = await http.PostAsync("https://app.disruptapi.com/v1/exposure/check", content);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());{
"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/watchlistscreates one, optionally with up to 1,000 items. If any item is invalid, nothing is created.POST /v1/watchlists/{id}/itemsadds or replaces 1 to 1,000 items per call. The response says how many werestoredand how many werenew.DELETE /v1/watchlists/{id}/items/{item_id}removes one item.GET /v1/watchlists/{id}/exposurereturns only the items that are exposed right now, each with itswatchlist_id.- A webhook with
"watchlists": ["*"](or a list of watchlist ids) fires when a signal touches any of their items. See Webhooks.
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"
}
]
}'// Node.js 18+ (built-in fetch), saved as an .mjs file
const res = await fetch("https://app.disruptapi.com/v1/watchlists/wl_3f9a1c2b7d4e5f60/items", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DISRUPT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{
id: "BKG-7QX2LM",
kind: "flight",
carrier: "AS",
origin: "SEA",
destination: "HNL",
depart_at: "2026-11-22T08:00:00Z",
},
],
}),
signal: AbortSignal.timeout(30_000),
});
const json = await res.json();
if (!res.ok) {
throw new Error(`${res.status} ${json.error.code}: ${json.error.message}`);
}
console.log(JSON.stringify(json.data, null, 2));import os
import requests
resp = requests.post(
"https://app.disruptapi.com/v1/watchlists/wl_3f9a1c2b7d4e5f60/items",
headers={"Authorization": f"Bearer {os.environ['DISRUPT_KEY']}"},
json={
"items": [
{
"id": "BKG-7QX2LM",
"kind": "flight",
"carrier": "AS",
"origin": "SEA",
"destination": "HNL",
"depart_at": "2026-11-22T08:00:00Z",
},
],
},
timeout=30,
)
if not resp.ok:
err = resp.json()["error"]
raise SystemExit(f"{resp.status_code} {err['code']}: {err['message']}")
print(resp.json()["data"])import os
import httpx
with httpx.Client(
base_url="https://app.disruptapi.com",
headers={"Authorization": f"Bearer {os.environ['DISRUPT_KEY']}"},
timeout=30,
) as client:
resp = client.post(
"/v1/watchlists/wl_3f9a1c2b7d4e5f60/items",
json={
"items": [
{
"id": "BKG-7QX2LM",
"kind": "flight",
"carrier": "AS",
"origin": "SEA",
"destination": "HNL",
"depart_at": "2026-11-22T08:00:00Z",
},
],
},
)
if resp.is_error:
err = resp.json()["error"]
raise SystemExit(f"{resp.status_code} {err['code']}: {err['message']}")
print(resp.json()["data"])package main
import (
"bytes"
"fmt"
"io"
"log"
"net/http"
"os"
"time"
)
func main() {
body := []byte(`{
"items": [
{
"id": "BKG-7QX2LM",
"kind": "flight",
"carrier": "AS",
"origin": "SEA",
"destination": "HNL",
"depart_at": "2026-11-22T08:00:00Z"
}
]
}`)
req, err := http.NewRequest(http.MethodPost, "https://app.disruptapi.com/v1/watchlists/wl_3f9a1c2b7d4e5f60/items", bytes.NewReader(body))
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("DISRUPT_KEY"))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 30 * time.Second}
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
out, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.StatusCode, string(out))
}require "json"
require "net/http"
require "uri"
uri = URI("https://app.disruptapi.com/v1/watchlists/wl_3f9a1c2b7d4e5f60/items")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("DISRUPT_KEY")}"
req["Content-Type"] = "application/json"
req.body = <<~JSON
{
"items": [
{
"id": "BKG-7QX2LM",
"kind": "flight",
"carrier": "AS",
"origin": "SEA",
"destination": "HNL",
"depart_at": "2026-11-22T08:00:00Z"
}
]
}
JSON
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
http.request(req)
end
json = JSON.parse(res.body)
abort "#{res.code} #{json["error"]["code"]}: #{json["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts JSON.pretty_generate(json["data"])<?php
$payload = <<<'JSON'
{
"items": [
{
"id": "BKG-7QX2LM",
"kind": "flight",
"carrier": "AS",
"origin": "SEA",
"destination": "HNL",
"depart_at": "2026-11-22T08:00:00Z"
}
]
}
JSON;
$ch = curl_init("https://app.disruptapi.com/v1/watchlists/wl_3f9a1c2b7d4e5f60/items");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("DISRUPT_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $payload,
]);
$raw = curl_exec($ch);
if ($raw === false) {
exit("request failed: " . curl_error($ch) . PHP_EOL);
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($raw, true);
if ($status >= 400) {
exit("{$status} {$json['error']['code']}: {$json['error']['message']}" . PHP_EOL);
}
print_r($json["data"]);// Java 17+. Run with: java Main.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
public class Main {
public static void main(String[] args) throws Exception {
String body = """
{
"items": [
{
"id": "BKG-7QX2LM",
"kind": "flight",
"carrier": "AS",
"origin": "SEA",
"destination": "HNL",
"depart_at": "2026-11-22T08:00:00Z"
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://app.disruptapi.com/v1/watchlists/wl_3f9a1c2b7d4e5f60/items"))
.timeout(Duration.ofSeconds(30))
.header("Authorization", "Bearer " + System.getenv("DISRUPT_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}// .NET 7+ console app (top-level statements, C# 11 raw strings)
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("DISRUPT_KEY"));
var body = """
{
"items": [
{
"id": "BKG-7QX2LM",
"kind": "flight",
"carrier": "AS",
"origin": "SEA",
"destination": "HNL",
"depart_at": "2026-11-22T08:00:00Z"
}
]
}
""";
using var content = new StringContent(body, Encoding.UTF8, "application/json");
using var response = await http.PostAsync("https://app.disruptapi.com/v1/watchlists/wl_3f9a1c2b7d4e5f60/items", content);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());{ "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.
| Item | Expires |
|---|---|
expires_at is set | At expires_at. |
| flight or trip | One 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#
| Limit | Value |
|---|---|
| Items per exposure check | 500 |
| Items per watchlist create or add call | 1,000 |
| Item size | 4 KB as JSON |
legs per item | 20 |
carriers, via, countries entries | 50 each |
radius_km | above 0, at most 500 (default 75) |
Watchlist name / description | 1 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.