Run endpoint health checks (beta)

Magic Transit uses endpoint health checks to determine the overall health of your inter-network connections. Probes originate from Cloudflare infrastructure, outside customer network namespaces, and target IP addresses deep within your network, beyond the tunnel-terminating border router. These "long distance" probes are purely diagnostic.

When choosing which endpoint IP addresses to monitor with health checks, use these guidelines:

• Provide one IP address for each of the prefixes Cloudflare advertises.
• Redundant IPs routed through the same ISP (Internet Service Provider) and infrastructure are not necessary but are useful when troubleshooting.

Cloudflare pings health check IPs from within the published Cloudflare IP range ↗, which is also available through the Cloudflare API.

When configuring an endpoint health check for an IP prefix, select an IP address within the range of that IP prefix. Refer to the table for an example of an endpoint health check configuration.

Prefix	Endpoint IP address
103.21.244.0/24	103.21.244.100
103.21.245.0/24	103.21.245.100

Refer to Tunnel health checks for more information.

Configure endpoint health checks (beta)

You can only configure endpoint health checks through the Cloudflare API. They are not available in the dashboard. Currently, configuring health checks is a beta feature.

Refer to the API documentation to learn how to create, list, and delete endpoint health checks. The following example creates a new endpoint health check.

Note

You will need your account ID and API token to use the API.

curl "https://api.cloudflare.com/client/v4/accounts/account_id/diagnostics/endpoint-healthcheck" \
  --request POST \
  --json '{
    "check_type": "icmp",
    "endpoint": "8.31.160.1"
  }'

{
    "result": {
        "id": "<HEALTH_CHECK_ID>",
        "check_type": "icmp",
        "endpoint": "8.31.160.1"
    },
    "success": true,
    "errors": [],
    "messages": []
}

Query GraphQL endpoint health checks

You can also use GraphQL to query endpoints within your network. This shows whether an IP within your network is reachable, and also set alerts in case there is a problem.

You can query the following categories:

• checkId: The ID of the check associated with the health check.
• checkType: The type of check associated with the health check.
• date: The health check event timestamp truncated to the day.
• datetime: The health check event timestamp.
• datetimeFifteenMinutes: The health check event timestamp truncated to multiples of 15 minutes.
• datetimeFiveMinutes: The health check event timestamp truncated to multiples of five minutes.
• datetimeHalfOfHour: The health check event timestamp truncated to multiples of 30 minutes.
• datetimeHour: The health check event timestamp truncated to the hour.
• datetimeMinute: The health check event timestamp truncated to the minute.
• endpoint: The endpoint of the check associated with the health check.

Refer to the example to learn how to create a query to check your endpoint's health:

query Viewer {
    viewer {
        accounts(filter: { accountTag: "YOUR_ACCOUNT_TAG" }) {
            magicEndpointHealthCheckAdaptiveGroups(
                filter: { date_geq: "2025-05-10" }
                limit: 10
            ) {
                count
                dimensions {
                    checkId
                    checkType
                    date
                    datetime
                    datetimeFifteenMinutes
                    datetimeFiveMinutes
                    datetimeHalfOfHour
                    datetimeHour
                    datetimeMinute
                    endpoint
                }
                sum {
                    failures
                    total
                }
            }
        }
    }
}

Configure alerts for endpoint health checks

You can set up alerts to be notified when the state of your endpoint's health is below a threshold defined by you.

1. Make a GET request to get a list of IDs for all of the endpoint health checks configured:

curl "https://api.cloudflare.com/client/v4/accounts/%3Caccount%20id%3E/diagnostics/endpoint-healthcheck" \
  --request GET

{
    "result": [
        {
            "id": "<HEALTH_CHECK_ID>",
            "check_type": "icmp",
            "endpoint": "8.31.160.1"
        }
    ],
    "success": true,
    "errors": [],
    "messages": []
}

2. Take note of the id value for the endpoint you want to get alerts for.
3. In the Cloudflare dashboard, go to the Notifications page.

Go to Notifications

4. Select Add.
5. From the drop-down menu, select Magic Transit.
6. Select Magic Endpoint Health Check Alert.
7. Provide a name for your new notification and optionally provide a description.
8. In the Service Level Objective (SLO) drop-down menu, select the SLO threshold for your notification. The SLO defines the percentage of endpoint health checks that must pass. If the number of passing endpoint health checks falls below the SLO, Cloudflare generates an alert:
   • High - 99%
   • Medium - 98%
   • Low - 97%
9. In the drop-down menu below SLOs, select the id value that matches the id you got through the API in step 1. This id should match the endpoint health check you want to get notifications for.
10. Select your preferred notification method (such as email or webhooks).
11. Select Save.

You will now receive notifications through your preferred method whenever the SLO for your endpoint health checks falls below your chosen threshold.