Network & DNS
/api/v1/pingPacketFlo Ping API
Round-trip time and packet loss to any host or IP using ICMP echo by default, or TCP connect on a specified port.
| Parameter | Type | Required | Description |
|---|---|---|---|
host | string | Yes | Hostname or IP address to ping. |
mode | string | No | Ping mode: "icmp" (default) sends 4 ICMP echo packets; "tcp" performs TCP connection handshakes. |
port | number | No | Target port when mode="tcp" (1–65535, default 443). Ignored when mode="icmp". |
ICMP Echo (Default)
Sends 4 ICMP echo packets to test latency and packet loss.
Example request
curl "https://packetflo.io/api/v1/ping?host=1.1.1.1&api_key=YOUR_API_KEY"
Example response
{ "ok": true, "data": { "host": "1.1.1.1", "ip": "1.1.1.1", "reverseDns": "one.one.one.one", "protocol": "icmp", "addressFamily": "IPv4", "probe": { "id": "default", "label": "PacketFlo probe", "region": null }, "status": "Online", "text": "Pinging one.one.one.one [1.1.1.1] with 64 bytes of data:\nReply from 1.1.1.1: bytes=64 time=20.3ms TTL=59\nReply from 1.1.1.1: bytes=64 time=20.0ms TTL=59\nReply from 1.1.1.1: bytes=64 time=20.1ms TTL=59\nReply from 1.1.1.1: bytes=64 time=19.3ms TTL=59\n\nPing statistics for 1.1.1.1:\n Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),\nApproximate round trip times in milli-seconds:\n Minimum = 19.3ms, Maximum = 20.3ms, Average = 20ms", "sent": 4, "received": 4, "lost": 0, "lossPercent": 0, "min": 19.3, "max": 20.3, "average": 20 }, "meta": { "tool": "ping", "version": "v1" } }
TCP Connect
Performs TCP handshakes on the target port to test reachability when ICMP is filtered or blocked.
Example request
curl "https://packetflo.io/api/v1/ping?host=1.1.1.1&mode=tcp&port=443&api_key=YOUR_API_KEY"
Example response
{ "ok": true, "data": { "host": "1.1.1.1", "ip": "1.1.1.1", "mode": "tcp", "protocol": "tcp", "addressFamily": "IPv4", "probe": { "id": "default", "label": "PacketFlo probe", "region": null }, "port": 443, "sent": 4, "connected": 4, "successPercent": 100, "min": 16, "max": 25, "average": 21, "probes": [ { "status": "Open", "timeMs": 16 }, { "status": "Open", "timeMs": 25 }, { "status": "Open", "timeMs": 22 }, { "status": "Open", "timeMs": 20 } ], "status": "Open" }, "meta": { "tool": "ping", "version": "v1" } }
Reading the result
In ICMP mode (default), Online means at least one probe replied, and No ICMP reply means none replied. In TCP mode, Open means all connections succeeded, Partial means some connected, and Closed / Timeout indicates a rejected or dropped connection.
Response fields
| Field | What it tells you |
|---|---|
host / ip / reverseDns | Input, selected public address and optional reverse DNS name. |
mode / port | mode is "tcp" when requested along with the target port; omitted for default ICMP ping. |
sent / received / lost / lossPercent | Packet counts and loss percentage for ICMP mode. |
connected / failed / successPercent | Connection counts and success rate for TCP mode. |
min / max / average | Round-trip / connect times in milliseconds; null when no replies or connections were received. |
text | Human-readable transcript for ICMP mode. Use structured fields for automation. |
Scope and limits
Sends four sequential probes from PacketFlo's server to one resolved IP. In ICMP mode (default), sends 4 ICMP echo packets. In TCP mode, performs TCP connection handshakes to the requested port.
Authentication and errors
Send your key in the x-api-key header, or the supported api_key query parameter. Each request uses 2 credits from the key's shared 300-credit rolling 24-hour budget. Credits are charged before parameter validation. Successful responses and quota errors include usage headers; GET and OPTIONS support CORS.
| API status | Meaning |
|---|---|
200 | The diagnostic returned a result in data, with ok: true and version information in meta. Read the diagnostic fields to determine the target's condition. |
400 | Invalid or blocked input, or a lookup/check failure that could not be returned as a diagnostic result. Read error for details. |
401 | Missing, invalid or revoked API key. |
429 | The request would exceed the key's available credit budget. |