# 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.

> product: pearl-family · topic: specs-ports · source: pearl-rest-api.md · updated: Oct 7, 2026