Documentation

Quick start

Get a key, create a monitor, start getting checks. No registration. Your key is your account.

Step 1: Generate a key

Go to pingdog.net and click "Get my free monitoring key". Your key starts with pdk_. Save it — it is not stored anywhere else.

Step 2: Create your first monitor

curl -X POST https://api.pingdog.net/api/monitors \
  -H "X-API-Key: pdk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "type": "http",
    "url":  "https://api.example.com/health",
    "interval_seconds": 300
  }'

Step 3: View results

curl https://api.pingdog.net/api/monitors/pdk_KEYHASH \
  -H "X-API-Key: pdk_YOUR_KEY"

Check types

PingDog supports 7 check types. The type field in the monitor object controls which logic is used.

Type value	What it checks	Unique?
`http`	HTTP/HTTPS status code, response time, body match
`tcp`	TCP port open, connect time
`dns`	DNS resolution time, resolved IPs
`ssl`	Certificate validity, days until expiry
`rpc`	Block height, sync status, staleness	Only PingDog
`a2a`	Agent card discovery, capabilities, ping	Only PingDog
`mcp`	WebSocket connect, tools/list, response time	Only PingDog

HTTP / HTTPS

Makes an HTTP request and validates the response. Optional: match a string in the response body.

{
  "type": "http",
  "url": "https://api.example.com/health",
  "method": "GET",               // GET or POST
  "expect_status": 200,          // default 200
  "expect_body": "\"ok\":true"   // optional substring match
}

TCP Port

Attempts a TCP connection to the host and port. Pass the target as tcp://host:port.

{
  "type": "tcp",
  "url": "tcp://db.example.com:5432"
}

DNS

Resolves the hostname and checks the answer. Useful for detecting DNS hijacking or propagation failures.

{
  "type": "dns",
  "url": "https://example.com"    // hostname extracted automatically
}

SSL Certificate

Connects via TLS and reads the certificate expiry date. You are alerted when ssl_days_left falls below thresholds (30d, 7d, 1d on Pro+).

{
  "type": "ssl",
  "url": "https://example.com"
}

RPC Health Only PingDog

Calls eth_blockNumber on the RPC endpoint and checks: valid JSON-RPC response, block height is a valid hex number, and the block is not stale (moving forward over time).

{
  "type": "rpc",
  "url": "https://mainnet.infura.io/v3/YOUR_KEY"
}

Result fields include: block_number, is_syncing, is_stale (true if the block did not advance vs previous check).

A2A Agent Only PingDog

Performs a 3-step health check on an A2A-compatible AI agent:

GET /.well-known/agent-card.json — must return valid JSON
Verifies the card has name, capabilities, and endpoint fields
POSTs a minimal ping to the agent endpoint and checks for a response

{
  "type": "a2a",
  "url": "https://agent.example.com"
}

MCP Server Only PingDog

Connects via WebSocket and verifies the MCP server can list its tools. The check times out if the connection fails or tools/list returns no response within the timeout window.

{
  "type": "mcp",
  "url": "wss://mcp.example.com/ws"
}

API Reference

Base URL: https://api.pingdog.net

All requests require the header X-API-Key: pdk_YOUR_KEY.

Monitors

POST/api/monitors

Create a new monitor.

Request body:

{
  "name":             "My API",        // required
  "type":             "http",         // required: http|tcp|dns|ssl|rpc|a2a|mcp
  "url":              "https://...",  // required
  "interval_seconds": 300,            // 300|60|30 (tier-limited)
  "timeout_ms":       10000,          // optional, default 10000
  "method":           "GET",          // http only: GET|POST
  "expect_status":    200,            // http only
  "expect_body":      "ok",           // http only, substring match
  "regions":          ["ca", "de"],   // optional: ca|de|sg|uk
  "webhook_url":      "https://...", // optional alert destination
  "telegram_chat_id": "-100123456"  // optional
}

GET/api/monitors/:keyHash

List all active monitors for your key. The keyHash is SHA-256 of your key (hex, first 16 chars). Available in the account page.

PUT/api/monitors/:id

Update a monitor. Pass only the fields you want to change.

DELETE/api/monitors/:id

Soft-delete a monitor. History is retained for 30 days.

Results

GET/api/results/:monitorId

Get check results for a monitor. Query params: limit (default 100, max 1000), location (filter by region).

Status page

GET/api/status/:keyHash

Public status page data. Returns all monitors the customer marked public, with uptime percentages and incident history. No auth required.

Consensus algorithm

PingDog runs checks from multiple geographic locations simultaneously. A service is only declared DOWN when a majority of locations agree it is unreachable.

4 regions: 3 or more must report failure
3 regions: 2 or more must report failure
2 regions (free tier): both must report failure

This prevents false positives from transient routing issues, DNS hiccups, or regional packet loss that only affects one location.

Alert configuration

Alerts fire when consensus declares a state change (UP → DOWN or DOWN → UP).

Webhook

Set webhook_url on any monitor. PingDog will POST the following JSON body:

{
  "monitor_id":   "abc123",
  "monitor_name": "My API",
  "status":       "down",       // "up" or "down"
  "locations":    ["ca", "de", "sg"],
  "latency_ms":   null,
  "error":        "Connection refused",
  "timestamp":    "2026-04-12T14:23:00Z"
}

Get a bot token from @BotFather and find your chat ID using @userinfobot. Set telegram_chat_id on any monitor. PingDog will send a message like:

🔴 DOWN — My API
Confirmed from: Canada, Germany, Singapore
Error: Connection refused
Time: 2026-04-12 14:23 UTC

Public status pages

Every account gets a public status page at:

https://pingdog.net/status.html?k=YOUR_KEY_HASH

Share this URL with customers. It shows all monitors you marked public, with green/red dot indicators, uptime percentage, and response time trend.

Monitors are private by default. Set "public": true on any monitor to include it on the status page.

Install as app (PWA)

PingDog is a Progressive Web App. On mobile, open pingdog.net and tap "Add to Home Screen" — it installs like a native app with offline support.

On desktop Chrome: click the install icon in the address bar.

Billing

Free tier is free forever, no payment needed. To upgrade to Pro or Business:

Go to account.html and enter your key
Click "Upgrade" and connect your wallet (MetaMask, Rabby, or any EIP-1193 wallet)
Approve our billing contract for USDC or USDT on Demo L2 (chain 845302)
We pull the monthly subscription. Your funds stay in your wallet until we pull.

Cancel at any time by revoking the USDC/USDT approval in your wallet. No forms, no emails.

Code examples

Node.js

const res = await fetch('https://api.pingdog.net/api/monitors', {
  method: 'POST',
  headers: {
    'X-API-Key':       'pdk_YOUR_KEY',
    'Content-Type':   'application/json',
  },
  body: JSON.stringify({
    name:             'My RPC Node',
    type:             'rpc',
    url:              'https://mainnet.infura.io/v3/KEY',
    interval_seconds: 60,
  }),
});
const monitor = await res.json();
console.log(monitor.id);

Python

import httpx

resp = httpx.post(
    "https://api.pingdog.net/api/monitors",
    headers={"X-API-Key": "pdk_YOUR_KEY"},
    json={
        "name": "My A2A Agent",
        "type": "a2a",
        "url":  "https://agent.example.com",
        "interval_seconds": 300,
    },
)
print(resp.json())

curl — list all monitors

curl https://api.pingdog.net/api/monitors/YOUR_KEY_HASH \
  -H "X-API-Key: pdk_YOUR_KEY" | jq .