Pearl REST API test network connectivity and measure bandwidth
Two network endpoints help diagnose a Pearl device that streams poorly or cannot reach a service. One reports the state of individual connectivity checks; the other runs an active speed test.
Applies to: Pearl-2, Pearl Mini, Pearl Nexus, Pearl Nano.
Connectivity details.
GET /api/v2.0/system/connectivity/details
The response reports external_ip and mdns, plus a state for each check. Each check returns disabled, ok, or error:
| Check | What it covers |
|---|---|
dns |
Name resolution |
http / https |
Outbound web access |
captive_portal |
Captive portal detection |
icmp |
Ping reachability |
epiphan_edge |
Connectivity to Epiphan Edge |
vtun |
Tunnel connectivity |
An error on icmp or dns alongside ok on http and https is common on networks that block ping or force a proxy, so read the checks together rather than treating any single error as a fault.
Speed test.
GET /api/v2.0/system/connectivity/tools/speedtest?mode=uplink&protocol=tcp&timeout=30
| Parameter | Values | Default |
|---|---|---|
mode |
uplink or downlink |
uplink |
protocol |
tcp or udp |
tcp |
timeout |
Maximum test duration in seconds, minimum 1 | 30 |
The result reports protocol, mode, bandwidth in bits per second, bitrate_limit in bits per second, and duration in seconds. A UDP test also returns a udp.loss figure.
An invalid protocol or mode returns HTTP 400 with the message Invalid protocol parameter or Invalid mode parameter.
Run the speed test when the device is idle. It generates real traffic and will compete with live streaming for the same uplink.