API reference

Network

The RF channel plan, what changed around a time, and everything known about an IP address.

List RF channels GET /v1/channels
List what changed around a time GET /v1/events
Look up an IP address GET /v1/ip/{ip}

List RF channels

GET /v1/channels Try it

Your RF channel plan: every wireless radio's centre frequency, channel width and duplex, with live signal, noise and MCS. overlap_candidates lists the other radios whose channels overlap it, which is handy for chasing interference and planning channels. Overlap only means the channels collide; whether the radios can hear each other depends on where they are and which way they point. Pass infid to also get that device's channel history. Radios that haven't reported in 7 days are left out, and at most 10,000 radios are considered.

Parameters

isp string query

ISP code from GET /isps. Optional when the key reaches exactly one ISP.
site integer or string query

Restrict to radios at this site: site_id or site code
infid integer query

Restrict to one device and include its channel change history
limit integer query

Max radios per page (default 200, max 500)
cursor string query

next_cursor from the previous page

Response

Also available as CSV: add format=csv. Columns follow the field order below, with nested fields as dotted columns (ap.name).

Paged: pass next_cursor back as cursor for the next page.

count integer
next_cursor string nullable

Pass as cursor to get the next page; null on the last page
radios array of objects
Each item: 13 fields
- device object
  
  The radio
  2 fields
  - infid integer
  - name string
- site object nullable
  
  The site
  3 fields
  - site_id integer
  - code string
    
    The ISP's short site code
  - name string
- radio string
  
  Radio group on the device
- center_mhz number
- width_mhz number
- range_mhz string nullable
  
  e.g. 5170-5190
- duplex string
- chains integer
- signal_dbm number nullable
  
  Worst chain
- noise_dbm number nullable
  
  Worst chain
- mcs number nullable
  
  Lowest chain
- as_of date-time
- overlap_candidates array of objects
  
  Radios in this result whose channel overlaps this one's (spectral collision only)
  Each item: 3 fields
  - device object
    
    The other radio
    
    2 fields
    
    infid integer
    
    name string
  - site object nullable
    
    The site
    
    3 fields
    
    site_id integer
    
    code string
    
    The ISP's short site code
    
    name string
  - center_mhz number
channel_history array of objects optional

With infid only: up to 30 changes, newest first
Each item: 5 fields
- radio string
- center_mhz number
- width_mhz number
- duplex string
- observed_at date-time

Example

curl -H "Authorization: Bearer $SWIFTFOX_KEY" \
  "https://api.swiftfox.net/v1/channels?isp=yourisp"

Response (example data):

{
  "count": 2,
  "next_cursor": null,
  "radios": [
    {
      "device": {
        "infid": 230,
        "name": "Hilltop Sector 1"
      },
      "site": {
        "site_id": 7,
        "code": "HT",
        "name": "Hilltop Tower"
      },
      "radio": "Wireless",
      "center_mhz": 5745,
      "width_mhz": 40,
      "range_mhz": "5725-5765",
      "duplex": "Half",
      "chains": 2,
      "signal_dbm": null,
      "noise_dbm": -94,
      "mcs": null,
      "as_of": "2026-10-08T22:10:05Z",
      "overlap_candidates": [
        {
          "device": {
            "infid": 318,
            "name": "Mill Valley Sector 2"
          },
          "site": {
            "site_id": 9,
            "code": "MV",
            "name": "Mill Valley Tower"
          },
          "center_mhz": 5755
        }
      ]
    },
    {
      "device": {
        "infid": 318,
        "name": "Mill Valley Sector 2"
      },
      "site": {
        "site_id": 9,
        "code": "MV",
        "name": "Mill Valley Tower"
      },
      "radio": "Wireless",
      "center_mhz": 5755,
      "width_mhz": 20,
      "range_mhz": "5745-5765",
      "duplex": "Half",
      "chains": 2,
      "signal_dbm": null,
      "noise_dbm": -91,
      "mcs": null,
      "as_of": "2026-10-08T22:10:02Z",
      "overlap_candidates": [
        {
          "device": {
            "infid": 230,
            "name": "Hilltop Sector 1"
          },
          "site": {
            "site_id": 7,
            "code": "HT",
            "name": "Hilltop Tower"
          },
          "center_mhz": 5745
        }
      ]
    }
  ]
}

List what changed around a time

GET /v1/events Try it

Everything that changed around a time: radio channel and width changes (tracked separately from config backups), config changes, issues that started or ended in the window, and issues that started in it and are still open. Repeats of the same issue are folded into one entry with occurrences and total_minutes_in_state. Use it to line an outage, or a step in a graph, up with what caused it. Narrow it down with type, or with metric_q to match issue names (for example Ping or Usage). The window is centred on timestamp and up to 48 hours wide; issue history goes back about 90 days and config history about a year.

Parameters

isp string query

ISP code from GET /isps. Optional when the key reaches exactly one ISP.
timestamp integer or string query required

Center of the window: unix seconds or 'YYYY-MM-DD HH:MM:SS' UTC
window_hours integer query

Total window width in hours, centered on timestamp (default 4, max 48)
type one of: "device", "backhaul", "cpe" query

Restrict the issue sections to device, backhaul or cpe (config and channel changes are always shown)
metric_q string query

Substring filter on issue metric names, e.g. 'Ping' or 'Usage' — use to cut peak-hour usage-warning noise

Response

window object
3 fields
- from date-time
- to date-time
- centered_on date-time
channel_changes array of objects
Each item: 7 fields
- device object
  
  The radio
  2 fields
  - infid integer
  - name string
- site object nullable
  
  The site
  3 fields
  - site_id integer
  - code string
    
    The ISP's short site code
  - name string
- radio string
- center_mhz number
- width_mhz number
- duplex string
- observed_at date-time
config_changes array of objects
Each item: 5 fields
- device object
  
  The device
  2 fields
  - infid integer
  - name string
- revision integer
- changed_at date-time
- format string
- size_bytes integer
resolved_issues_overlapping array of one of several shapess
A single occurrence: 8 fields
- type string
  
  device, backhaul or cpe; more types may be added
- entity_id integer
  
  The infid, bhid or cpeid, by type
- name string
- metric string
- severity one of: "info", "warning", "outage", "critical" nullable
  
  info, warning, outage or critical; outage and critical would page
- details string
- started_at date-time
- ended_at date-time
Repeats of one entity + metric, folded: 11 fields
- type string
  
  device, backhaul or cpe; more types may be added
- entity_id integer
  
  The infid, bhid or cpeid, by type
- name string
- metric string
- severity one of: "info", "warning", "outage", "critical" nullable
  
  info, warning, outage or critical; outage and critical would page
- flapping boolean
- occurrences integer
- first_started_at date-time
- last_ended_at date-time
- total_minutes_in_state integer
- latest_details string
active_issues_started_in_window array of objects
Each item: 7 fields
- type string
  
  device, backhaul or cpe; more types may be added
- entity_id integer
  
  The infid, bhid or cpeid, by type
- name string
- metric string
- severity one of: "info", "warning", "outage", "critical" nullable
  
  info, warning, outage or critical; outage and critical would page
- details string
- started_at date-time

Example

curl -H "Authorization: Bearer $SWIFTFOX_KEY" \
  "https://api.swiftfox.net/v1/events?isp=yourisp&timestamp=…"

Response (example data):

{
  "window": {
    "from": "2026-10-08T20:00:00Z",
    "to": "2026-10-08T22:00:00Z",
    "centered_on": "2026-10-08T21:00:00Z"
  },
  "channel_changes": [
    {
      "device": {
        "infid": 230,
        "name": "Hilltop Sector 1"
      },
      "site": {
        "site_id": 7,
        "code": "HT",
        "name": "Hilltop Tower"
      },
      "radio": "Wireless",
      "center_mhz": 5745,
      "width_mhz": 40,
      "duplex": "Half",
      "observed_at": "2026-10-08T20:41:06Z"
    }
  ],
  "config_changes": [
    {
      "device": {
        "infid": 214,
        "name": "Hilltop Router"
      },
      "revision": 1791449932,
      "changed_at": "2026-10-08T20:38:52Z",
      "format": "mikrotik",
      "size_bytes": 15880
    }
  ],
  "resolved_issues_overlapping": [
    {
      "type": "backhaul",
      "entity_id": 12,
      "name": "RB-HT",
      "metric": "Backhaul:Ping Latency",
      "severity": "warning",
      "details": "Warning - 12.8 ms avg latency",
      "started_at": "2026-10-08T20:44:10Z",
      "ended_at": "2026-10-08T20:46:11Z"
    },
    {
      "type": "device",
      "entity_id": 230,
      "name": "Hilltop Sector 1",
      "metric": "Ping:Quality",
      "severity": "outage",
      "flapping": true,
      "occurrences": 4,
      "first_started_at": "2026-10-08T20:42:30Z",
      "last_ended_at": "2026-10-08T21:05:02Z",
      "total_minutes_in_state": 6,
      "latest_details": "Bad - 20% packet loss"
    }
  ],
  "active_issues_started_in_window": [
    {
      "type": "device",
      "entity_id": 230,
      "name": "Hilltop Sector 1",
      "metric": "Health:Temperature",
      "severity": "warning",
      "details": "Warning - 71 deg C",
      "started_at": "2026-10-08T21:40:12Z"
    }
  ]
}

Look up an IP address

GET /v1/ip/{ip} Try it

Everything we know about an IPv4 address in your network: what our collectors have seen recently (ARP, DHCP leases, CDP/LLDP neighbours, traffic flows and Ubiquiti discovery, the same data as the network map's IP hover, refreshed every few minutes), which device, interface or CPE it belongs to, with ids for get_device and get_cpe, and the network owner for public addresses when we already know it. No cache entry only means nothing has seen the address in the last few minutes, not that it's unused. Hostnames, discovered device names and comments can name subscribers, so they need the pii scope.

Parameters

ip string path required

Dotted IPv4 address
isp string query

ISP code from GET /isps. Optional when the key reaches exactly one ISP.

Response

ip string
is_private_or_reserved boolean
cache_entry object nullable
2 fields
- type string
  
  What the address is, as the cache classifies it
- sources object
  
  What each source saw, by source. A source kind not listed here may appear, with site, details and last_seen.
  9 fields
  - arp object optional
    
    In a router's ARP table
    
    5 fields
    
    seen_by object nullable
    
    The router with it in its ARP table
    
    3 fields
    
    infid integer nullable
    
    name string nullable
    
    site object nullable optional
    
    The site
    
    3 fields
    
    site_id integer
    
    code string
    
    The ISP's short site code
    
    name string
    
    interface string nullable
    
    mac string nullable
    
    mac_manufacturer string nullable
    
    last_seen date-time nullable
  - dhcp object optional
    
    A DHCP lease
    
    9 fields
    
    lease_on object nullable
    
    The DHCP server holding the lease
    
    3 fields
    
    infid integer nullable
    
    name string nullable
    
    site object nullable optional
    
    The site
    
    3 fields
    
    site_id integer
    
    code string
    
    The ISP's short site code
    
    name string
    
    interface string nullable
    
    hostname string nullable
    
    null without the pii scope
    
    mac string nullable
    
    dhcp_server string nullable
    
    static_lease boolean
    
    comment string nullable
    
    null without the pii scope
    
    lease_time_s number nullable
    
    last_seen date-time nullable
  - cdp object optional
    
    A CDP/LLDP/MNDP neighbour
    
    6 fields
    
    found_by object nullable
    
    The device that saw it as a neighbour
    
    3 fields
    
    infid integer nullable
    
    name string nullable
    
    site object nullable optional
    
    The site
    
    3 fields
    
    site_id integer
    
    code string
    
    The ISP's short site code
    
    name string
    
    interface string nullable
    
    identity string nullable
    
    null without the pii scope
    
    platform string nullable
    
    version string nullable
    
    last_seen date-time nullable
  - flow object optional
    
    Traffic flows (NetFlow)
    
    4 fields
    
    throughput_rx_tx_mbit string nullable
    
    packets_rx_tx_per_sec string nullable
    
    sessions_rx_tx string nullable
    
    as_of date-time nullable
  - ubnt object optional
    
    Ubiquiti discovery
    
    6 fields
    
    name string nullable
    
    null without the pii scope
    
    model string nullable
    
    firmware string nullable
    
    uptime string nullable
    
    ssid string nullable
    
    last_seen date-time nullable
  - cpe object optional
    
    The address of a CPE radio itself
    
    7 fields
    
    ap object nullable
    
    The CPE's access point
    
    3 fields
    
    infid integer nullable
    
    name string nullable
    
    site object nullable optional
    
    The site
    
    3 fields
    
    site_id integer
    
    code string
    
    The ISP's short site code
    
    name string
    
    cpe_mac string nullable
    
    mac_manufacturer string nullable
    
    account_name string nullable optional
    
    pii scope only
    
    cpe_description string nullable optional
    
    pii scope only
    
    cpe_discovered_name string nullable optional
    
    pii scope only
    
    last_seen date-time nullable
  - client object optional
    
    An address in a CPE's service package (shaping and disconnect)
    
    10 fields
    
    meaning string
    
    What the match means: the CPE itself, or a customer device behind it
    
    is_cpe_itself boolean nullable
    
    ap object nullable
    
    The CPE's access point
    
    3 fields
    
    infid integer nullable
    
    name string nullable
    
    site object nullable optional
    
    The site
    
    3 fields
    
    site_id integer
    
    code string
    
    The ISP's short site code
    
    name string
    
    cpe_mac string nullable
    
    device_mac string nullable
    
    device_mac_manufacturer string nullable
    
    account_name string nullable optional
    
    pii scope only
    
    cpe_description string nullable optional
    
    pii scope only
    
    cpe_discovered_name string nullable optional
    
    pii scope only
    
    last_seen date-time nullable
  - sn object optional
    
    The subnet it's in
    
    4 fields
    
    subnet string nullable
    
    gateway_router object nullable
    
    The router that's the subnet's gateway
    
    3 fields
    
    infid integer nullable
    
    name string nullable
    
    site object nullable optional
    
    The site
    
    3 fields
    
    site_id integer
    
    code string
    
    The ISP's short site code
    
    name string
    
    gateway_ip string nullable
    
    routers_on_subnet integer optional
  - infra object optional
    
    An address on one of your devices
    
    6 fields
    
    device object nullable
    
    The device
    
    3 fields
    
    infid integer nullable
    
    name string nullable
    
    site object nullable optional
    
    The site
    
    3 fields
    
    site_id integer
    
    code string
    
    The ISP's short site code
    
    name string
    
    device_class string nullable
    
    hardware_type object nullable
    
    The kind of device, which decides how Swift Fox collects from it
    
    2 fields
    
    id string
    
    e.g. mikrotik, ubiquiti, cambium, snmp (any standard-SNMP device), generic
    
    name string
    
    As the app shows it
    
    interface string nullable
    
    comment string nullable
    
    null without the pii scope
    
    last_seen date-time nullable
devices array of objects
Each item: 5 fields
- infid integer
- name string
- device_class string
- hardware_type object nullable
  
  The kind of device, which decides how Swift Fox collects from it
  2 fields
  - id string
    
    e.g. mikrotik, ubiquiti, cambium, snmp (any standard-SNMP device), generic
  - name string
    
    As the app shows it
- match string
interface_ips array of objects
Each item: 3 fields
- device object
  
  The device
  2 fields
  - infid integer
  - name string
- interface string nullable
- match string
cpes array of objects
Each item: 16 fields
- cpeid integer
- mac string
- ip string nullable
- ap object nullable
  
  The access point it's associated to
  2 fields
  - infid integer
  - name string
- site object nullable
  
  The access point's site
  3 fields
  - site_id integer
  - code string
    
    The ISP's short site code
  - name string
- account_number string nullable
  
  The customer-visible account number, as on invoices
- account_disconnected boolean nullable
- signal_dbm number nullable
- plan object nullable
  
  The billing plan and its configured rates
  4 fields
  - plan_id integer nullable
    
    Pass as plan to list_cpes
  - name string nullable
  - down_mbps number nullable
  - up_mbps number nullable
- effective_rate_mbps object nullable
  
  What the shaper applies right now: the plan reduced by congestion multipliers or usage caps
  2 fields
  - down number nullable
  - up number nullable
- monitored boolean
- last_assoc date-time nullable
- name string
  
  The subscriber's name with the pii scope; otherwise 'CPE <mac> (account <number>)'
- account_name string nullable optional
  
  pii scope only
- description string nullable optional
  
  pii scope only
- discovered_name string nullable optional
  
  pii scope only: the name the radio reports
external object nullable

Public IPs only
4 fields
- asn string nullable
- owner string nullable
- city string nullable
- region string nullable

Example

curl -H "Authorization: Bearer $SWIFTFOX_KEY" \
  "https://api.swiftfox.net/v1/ip/10.0.0.1?isp=yourisp"

Response (example data):

{
  "ip": "10.10.7.21",
  "is_private_or_reserved": true,
  "cache_entry": {
    "type": "infra",
    "sources": {
      "arp": {
        "seen_by": {
          "infid": 214,
          "name": "Hilltop Router",
          "site": {
            "site_id": 7,
            "code": "HT",
            "name": "Hilltop Tower"
          }
        },
        "interface": "bridge-sectors",
        "mac": "00:00:5E:00:53:21",
        "mac_manufacturer": "Cambium Networks Limited",
        "last_seen": "2026-10-08T22:13:05Z"
      },
      "infra": {
        "device": {
          "infid": 230,
          "name": "Hilltop Sector 1",
          "site": {
            "site_id": 7,
            "code": "HT",
            "name": "Hilltop Tower"
          }
        },
        "device_class": "AP",
        "hardware_type": {
          "id": "cambium",
          "name": "Cambium"
        },
        "interface": "br0",
        "comment": null,
        "last_seen": "2026-10-08T22:13:05Z"
      }
    }
  },
  "devices": [
    {
      "infid": 230,
      "name": "Hilltop Sector 1",
      "device_class": "AP",
      "hardware_type": {
        "id": "cambium",
        "name": "Cambium"
      },
      "match": "device main IP"
    }
  ],
  "interface_ips": [
    {
      "device": {
        "infid": 230,
        "name": "Hilltop Sector 1"
      },
      "interface": "br0",
      "match": "discovered interface IP"
    }
  ],
  "cpes": [],
  "external": null
}