Network & DNS

GET/api/v1/ping

PacketFlo Ping API

Cost: 2 credits per request

Round-trip time and packet loss to any host or IP using ICMP echo by default, or TCP connect on a specified port.

ParameterTypeRequiredDescription
hoststringYesHostname or IP address to ping.
modestringNoPing mode: "icmp" (default) sends 4 ICMP echo packets; "tcp" performs TCP connection handshakes.
portnumberNoTarget 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

FieldWhat it tells you
host / ip / reverseDnsInput, selected public address and optional reverse DNS name.
mode / portmode is "tcp" when requested along with the target port; omitted for default ICMP ping.
sent / received / lost / lossPercentPacket counts and loss percentage for ICMP mode.
connected / failed / successPercentConnection counts and success rate for TCP mode.
min / max / averageRound-trip / connect times in milliseconds; null when no replies or connections were received.
textHuman-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 statusMeaning
200The diagnostic returned a result in data, with ok: true and version information in meta. Read the diagnostic fields to determine the target's condition.
400Invalid or blocked input, or a lookup/check failure that could not be returned as a diagnostic result. Read error for details.
401Missing, invalid or revoked API key.
429The request would exceed the key's available credit budget.
Reverse DNS Lookup