Pagination and filtering
List endpoints page with limit and offset and return a meta block with the total. There are no cursors. For keeping a copy in sync, filter with since instead of re-reading every page.
How does pagination work?#
GET /v1/signals and GET /v1/events take limit (default 50) and offset (default 0) and return:
{
"data": ["..."],
"meta": { "total": 412, "limit": 50, "offset": 100 }
}totalcounts every result that matches the filters, not only this page.- You have reached the end when
offset + data.length >= total, or a page is empty. limitmust be 1 to 500 (else422 invalid_request) and at most your plan's page size: 50 on Sandbox, 200 on Starter, 500 on Pro and Enterprise (else400 limit_too_large).- Records returned count against your daily record budget.
curl "https://app.disruptapi.com/v1/signals?type=weather,natural_hazard&country=ES&limit=50&offset=50" \
-H "Authorization: Bearer $DISRUPT_KEY"// Node.js 18+ (built-in fetch), saved as an .mjs file
const res = await fetch("https://app.disruptapi.com/v1/signals?type=weather,natural_hazard&country=ES&limit=50&offset=50", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.DISRUPT_KEY}`,
},
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.get(
"https://app.disruptapi.com/v1/signals",
headers={"Authorization": f"Bearer {os.environ['DISRUPT_KEY']}"},
params={
"type": "weather,natural_hazard",
"country": "ES",
"limit": 50,
"offset": 50,
},
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.get(
"/v1/signals",
params={
"type": "weather,natural_hazard",
"country": "ES",
"limit": 50,
"offset": 50,
},
)
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 (
"fmt"
"io"
"log"
"net/http"
"os"
"time"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://app.disruptapi.com/v1/signals?type=weather,natural_hazard&country=ES&limit=50&offset=50", nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("DISRUPT_KEY"))
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/signals?type=weather,natural_hazard&country=ES&limit=50&offset=50")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("DISRUPT_KEY")}"
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
$ch = curl_init("https://app.disruptapi.com/v1/signals?type=weather,natural_hazard&country=ES&limit=50&offset=50");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("DISRUPT_KEY"),
],
]);
$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 {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://app.disruptapi.com/v1/signals?type=weather,natural_hazard&country=ES&limit=50&offset=50"))
.timeout(Duration.ofSeconds(30))
.header("Authorization", "Bearer " + System.getenv("DISRUPT_KEY"))
.GET()
.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"));
using var response = await http.GetAsync("https://app.disruptapi.com/v1/signals?type=weather,natural_hazard&country=ES&limit=50&offset=50");
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());Sort order#
| Endpoint | Order |
|---|---|
GET /v1/signals | Severity, highest first; then updated_at, newest first |
GET /v1/events | Landmark (anchor) events first; then starts_at, newest first |
GET /v1/watchlists/{id} | Items by last update, newest first |
Other bounded lists#
GET /v1/watchlists/{id}returns up tolimititems (1 to 1,000, default 100). It has no offset.- Exposure results return at most 20 matches per item;
match_countis the full number. GET /v1/airports/{iata}returns up to 100 active signals at the airport and 30 country-wide ones.GET /v1/usagetakesdays, 1 to 365 (default 30).
Filters on signals#
| Parameter | Type | Description |
|---|---|---|
status | string | active, resolved or all. Use all when syncing, so you also see resolutions. Default: active. |
type | string | One or more types, comma-separated: aviation,weather. Unknown types match nothing. |
min_severity | string | minor, moderate, severe or extreme. Includes higher severities. |
country | string | ISO 3166-1 alpha-2 code, any case. Signals whose countries include it. |
airport | string | IATA code, any case. Signals whose airports include it. |
provider | string | Exact provider id, lowercase: aws, cloudflare, faa. |
since | string | Only signals with updated_at at or after this UTC time. See the since format. |
limit | integer | 1 to 500, and at most your plan's page size. Default: 50. |
offset | integer | Number of results to skip. Default: 0. |
Filters combine with AND. Within type, any listed type matches.
Filters on events#
| Parameter | Type | Description |
|---|---|---|
provider | string | Exact provider id. |
failure_layer | string | A layer id from GET /v1/failure-layers. |
anchor_only | boolean | Only well-documented landmark events. Default: false. |
limit | integer | 1 to 500, and at most your plan's page size. Default: 50. |
offset | integer | Number of results to skip. Default: 0. |
How does since work?#
since returns signals whose updated_at is at or after the value. updated_at moves on every created, escalated, updated or resolved event, so since finds every material change.
- Send UTC in the same form the API returns:
2026-11-18T07:20:41Z. The value is compared as text, so time zone offsets such as+02:00and fractional seconds are not converted and give wrong results. A date alone,2026-11-18, works as the start of that day. - "At or after" means the newest signal you saw comes back again on the next poll. That is expected; skip it by
idandversion. - Combine with
status=all, or you will not see signals that resolved since your last poll.
How do I keep a local copy in sync?#
Poll with status=all and since set to the newest updated_at you have stored. Keep each signal at its highest version. Webhooks remove the need to poll; see polling or webhooks.
"""Keep a local copy of signals in sync by polling with since. Run every few minutes."""
from __future__ import annotations
import os
import requests
API = "https://app.disruptapi.com/v1/signals"
HEADERS = {"Authorization": f"Bearer {os.environ['DISRUPT_KEY']}"}
def sync(since: str | None, store: dict) -> str | None:
"""store maps signal id -> signal. Returns the next since value."""
params = {"status": "all", "limit": 200, "offset": 0} # Starter page size; use 50 on Sandbox
if since:
params["since"] = since
newest = since
while True:
resp = requests.get(API, headers=HEADERS, params=params, timeout=30)
resp.raise_for_status()
page = resp.json()
for sig in page["data"]:
known = store.get(sig["id"])
if known is None or sig["version"] > known["version"]:
store[sig["id"]] = sig # created, changed or resolved
if newest is None or sig["updated_at"] > newest:
newest = sig["updated_at"]
params["offset"] += len(page["data"])
if not page["data"] or params["offset"] >= page["meta"]["total"]:
return newest
store: dict = {}
cursor = sync(None, store) # first run: everything active or resolved, page by page
cursor = sync(cursor, store) # later runs: only what changed since the newest updated_at// Keep a local copy of signals in sync by polling with since. Run every few minutes.
const API = "https://app.disruptapi.com/v1/signals";
const headers = { Authorization: `Bearer ${process.env.DISRUPT_KEY}` };
export async function sync(since, store /* Map<id, signal> */) {
let offset = 0;
let newest = since;
for (;;) {
const params = new URLSearchParams({ status: "all", limit: "200", offset: String(offset) });
if (since) params.set("since", since);
const res = await fetch(`${API}?${params}`, { headers, signal: AbortSignal.timeout(30_000) });
if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error?.code}`);
const { data, meta } = await res.json();
for (const sig of data) {
const known = store.get(sig.id);
if (!known || sig.version > known.version) store.set(sig.id, sig);
if (!newest || sig.updated_at > newest) newest = sig.updated_at;
}
offset += data.length;
if (data.length === 0 || offset >= meta.total) return newest;
}
}Last updated 2026-11-18. Questions or a mistake on this page? Contact us.