> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uptimeio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ping (ICMP) Monitoring

> Check that a server or device is reachable on the network with ICMP ping

A ping monitor sends ICMP echo requests to a host and succeeds when the host replies. It tells you whether a machine is reachable, not whether a particular service on it is working.

## When to use it

* Confirm a server or network device is online
* Watch a VPN endpoint or router that has no open TCP port
* Pair with [Port](/monitors/port) and [HTTP](/monitors/http) monitors to see at which layer a problem is

<Note>
  Ping checks run from UptimeIO's probe locations over the public internet. The target must be publicly reachable: private and internal targets (private IP ranges such as 10.x, 172.16-31.x and 192.168.x, `localhost`, and names ending in `.local`, `.internal` or `.lan`) are rejected with a `VALIDATION_ERROR`.
</Note>

## Create a ping monitor

<Steps>
  <Step title="Enter the target">
    A public hostname or IP address, for example `vpn.yourcompany.com` or `203.0.113.10`.
  </Step>

  <Step title="Set interval and timeout">
    The interval minimum depends on your plan (Free 300 seconds, Pro and Scale 60 seconds).
  </Step>

  <Step title="Choose probe locations">
    UptimeIO probes from multiple [locations](/monitors/probe-locations). Pro and Scale can choose which locations run regular checks (at least one); Free uses automatic selection.
  </Step>
</Steps>

### Settings

| Field (API) | Description | Default |
| - | - | - |
| `name` | Monitor name, up to 80 characters | Required |
| `type` | `ICMP` | Required |
| `target` | Hostname or IP address | Required |
| `interval_seconds` | Seconds between checks (30 to 86,400, minimum set by plan) | Required |
| `timeout_ms` | Maximum wait, 1,000 to 60,000. Must be shorter than the check interval. | `10000` |
| `monitoring_regions` | Probe locations; `[]` for automatic. Free must send `[]` | Required |
| `icmp_config.ttl` | Time to live, 1 to 255 | system default |

<Info>
  Each check sends 3 echo requests. The check succeeds if at least one reply is received and fails when every packet is lost, the host cannot be resolved, or the timeout passes. `icmp_config.packet_count` and `icmp_config.packet_size` are accepted by the API but do not change the probe.
</Info>

### Example

```bash theme={null}
curl -X POST https://api.uptimeio.com/api/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VPN gateway",
    "type": "ICMP",
    "target": "vpn.yourcompany.com",
    "interval_seconds": 300,
    "timeout_ms": 10000,
    "monitoring_regions": []
  }'
```

## Results

Each check records whether it succeeded, the round-trip time, and packet statistics (packets sent and received, packet loss).

An incident opens when the host stays unreachable. Because incidents need confirmation from several probe locations, a failure seen from only one location does not open one (see [Understanding incidents](/essentials/understanding-incidents)).

## Firewalls

Allow inbound ICMP echo requests (type 8) and echo replies (type 0) to the host. Many cloud providers block ICMP by default, so add an explicit rule in your security group, network security group or firewall.

## Ping or port?

| | Ping (ICMP) | Port (TCP) |
| - | - | - |
| Checks | The host answers | A service accepts connections |
| Often blocked by firewalls | Yes | Rarely |
| Use for | "Is the server up?" | "Is the service up?" |

## Troubleshooting

<AccordionGroup>
  <Accordion title="100% packet loss">
    The host is down, ICMP is blocked, or the target is wrong. Check that the host is online, that the firewall allows ICMP, and try `ping hostname` from your own machine.
  </Accordion>

  <Accordion title="Unknown host">
    The name does not resolve. Check the spelling and the DNS records (`nslookup hostname`).
  </Accordion>

  <Accordion title="Timeouts">
    Raise `timeout_ms`, check for a firewall that silently drops ICMP, and try with a probe location closer to the host.
  </Accordion>

  <Accordion title="VALIDATION_ERROR on the target">
    The target is private, internal, a test domain or one of UptimeIO's own domains. Use a public hostname or IP.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Port Monitoring" icon="plug" href="/monitors/port">
    Monitor specific service ports
  </Card>

  <Card title="Notifications" icon="bell" href="/notifications/overview">
    Configure alerts for ping monitors
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.