API reference

Live tests

Ping and traceroute from a pingbox inside the network

Ping POST /v1/ping
Traceroute POST /v1/traceroute

Ping

POST /v1/ping Try it

Ping an IP address, hostname or device (by infid) from a pingbox inside your network. It sends count probes 200 ms apart and returns each probe plus a summary. You often won't need it: ping history for backhauls (almost continuous), devices (about every 10 seconds) and CPEs (about every minute) is already in get_device_history, get_backhaul_history and get_cpe_history (series pings). It's handy for addresses we don't monitor, a particular pingbox's point of view, or a quick burst. A device is pinged from the pingbox that monitors it and anything else from your network default, unless you pass a pingboxid from list_pingboxes. Hostnames are looked up in public DNS.

Needs the actions scope.

Parameters

isp string query

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

Request body

JSON.

target string or integer

Dotted IPv4, hostname, or device infid
count integer optional

Probes to send (default 10, max 20)
pingboxid integer optional

Pingbox to run from, from list_pingboxes (default: the device's own pingbox for an infid, otherwise your network default)

Response

target object
3 fields
- input string
- ip string
- name string nullable
  
  Device name for an infid, the hostname for a hostname
pingbox object

The pingbox the test ran from
2 fields
- pingboxid integer
- name string
sent integer
received integer
loss_pct number
rtt_ms object nullable

Milliseconds; null when nothing answered
3 fields
- min number
- avg number
- max number
probes array of objects
Each item: 3 fields
- rtt_ms number nullable
- ttl integer nullable
- error string nullable

Example

curl -X POST -H "Authorization: Bearer $SWIFTFOX_KEY" \
  -H "Content-Type: application/json" -d '{"target":"10.0.0.1"}' \
  "https://api.swiftfox.net/v1/ping?isp=yourisp"

Response (example data):

{
  "target": {
    "input": "230",
    "ip": "10.10.7.21",
    "name": "Hilltop Sector 1"
  },
  "pingbox": {
    "pingboxid": 1,
    "name": "Hilltop"
  },
  "sent": 3,
  "received": 3,
  "loss_pct": 0,
  "rtt_ms": {
    "min": 2.31,
    "avg": 2.6,
    "max": 3.02
  },
  "probes": [
    {
      "rtt_ms": 2.31,
      "ttl": 62,
      "error": null
    },
    {
      "rtt_ms": 2.47,
      "ttl": 62,
      "error": null
    },
    {
      "rtt_ms": 3.02,
      "ttl": 62,
      "error": null
    }
  ]
}

Traceroute

POST /v1/traceroute Try it

A traceroute from a pingbox inside your network to an IP address, hostname or device (by infid). It runs a few sweeps and merges them per hop with loss and latency, like MTR. Hops are labelled with your device names and infids, the backhaul crossed between two known devices (backhaul_from_prev, for get_backhaul), or the network owner for public hops when we already know it. Empty first sweeps are retried automatically (see rounds_completed). A device is traced from the pingbox that monitors it and anything else from your network default, unless you pass a pingboxid from list_pingboxes. Hostnames are looked up in public DNS.