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:

ResponseJSON
{
  "data": ["..."],
  "meta": { "total": 412, "limit": 50, "offset": 100 }
}
  • total counts 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.
  • limit must be 1 to 500 (else 422 invalid_request) and at most your plan's page size: 50 on Sandbox, 200 on Starter, 500 on Pro and Enterprise (else 400 limit_too_large).
  • Records returned count against your daily record budget.
Second page
curl "https://app.disruptapi.com/v1/signals?type=weather,natural_hazard&country=ES&limit=50&offset=50" \
  -H "Authorization: Bearer $DISRUPT_KEY"

Sort order#

EndpointOrder
GET /v1/signalsSeverity, highest first; then updated_at, newest first
GET /v1/eventsLandmark (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 to limit items (1 to 1,000, default 100). It has no offset.
  • Exposure results return at most 20 matches per item; match_count is the full number.
  • GET /v1/airports/{iata} returns up to 100 active signals at the airport and 30 country-wide ones.
  • GET /v1/usage takes days, 1 to 365 (default 30).

Filters on signals#

ParameterTypeDescription
statusstringactive, resolved or all. Use all when syncing, so you also see resolutions. Default: active.
typestringOne or more types, comma-separated: aviation,weather. Unknown types match nothing.
min_severitystringminor, moderate, severe or extreme. Includes higher severities.
countrystringISO 3166-1 alpha-2 code, any case. Signals whose countries include it.
airportstringIATA code, any case. Signals whose airports include it.
providerstringExact provider id, lowercase: aws, cloudflare, faa.
sincestringOnly signals with updated_at at or after this UTC time. See the since format.
limitinteger1 to 500, and at most your plan's page size. Default: 50.
offsetintegerNumber of results to skip. Default: 0.

Filters combine with AND. Within type, any listed type matches.

Filters on events#

ParameterTypeDescription
providerstringExact provider id.
failure_layerstringA layer id from GET /v1/failure-layers.
anchor_onlybooleanOnly well-documented landmark events. Default: false.
limitinteger1 to 500, and at most your plan's page size. Default: 50.
offsetintegerNumber 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:00 and 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 id and version.
  • 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.

Incremental sync
"""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

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