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 checks whether your target is up — reachable, healthy, and responding as expected. The type field in the monitor object controls which check logic is used.

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

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,            // any interval; faster = more checks = higher cost
  "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 (Australia — au — coming soon)
  "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. Detailed history is retained live during the paid period and purged about two weeks after it ends; small period summaries are kept as part of your history.

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.

Proof of work & multi-region

PingDog is built so that a working-but-silent monitor never looks the same as a broken one: it makes the work visible. Every check is counted, timestamped, and charted, and your dashboard headline is the live check count, uptime percentage, and latency trend — never an empty screen. The same numbers are reused in your alerts and end-of-period report, so you always hold the receipt for the vigilance you paid for.

Where a check runs from more than one region, PingDog compares the results before declaring a state change, so a transient blip in a single location does not fire a false alarm. A cross-region view also lets you distinguish a global outage from a "down from Europe, up from Asia" routing problem.

Alert configuration

Alerts fire when PingDog confirms 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.

Pricing & payment

PingDog is pay-as-you-go. You buy a fixed block of checks upfront and it runs until they are used up, then it ends. There is no subscription, no renewal, and no stored card.

The price is $0.0005 per check (USDC on Base, shown in dollars at 1:1). Your cost is just the number of checks you buy:

checks = duration ÷ interval
cost   = checks × $0.0005

# 1 target, every 5 min, 6 months
#   288/day × 183 days = 52,704 checks × $0.0005 = $26.35
# 1 target, every minute, 1 month
#   1,440/day × 30 days = 43,200 checks × $0.0005 = $21.60
# 1 target, every second, 2-hour burst
#   3,600/hr × 2 hr = 7,200 checks × $0.0005 = $3.60

Two levers move the price: frequency (5 min → 1 min → 5-10 s → ~1 s) and volume (number of targets — each billed independently on its own duration and interval). A free tier lets you run a few targets at a slow interval and expires three months after sign-up. Purchases start around $5.

To buy, open your dashboard, choose a target, interval, and duration, and pay the shown amount in USDC on Base — copy the address, scan the QR, or withdraw directly from an exchange. No wallet is required.

All sales are final. Because nothing recurs, there are no refunds and nothing to dispute. Send only the displayed amount, on the Base network, to the live address for your order before it expires — stray, duplicate, or wrong-network payments cannot be refunded.

Recovery

Your key owns your monitors. If you added an email, request a magic link from the dashboard and we email you a one-time link back in — no password. If you did not add an email, your key and bookmarked dashboard link are the only way back, so keep them safe.

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 .

Live demos

Click "Run demo" to fire a real check from your browser against the target host. Latency is measured end-to-end (DNS + TCP + TLS + HTTP round-trip). No key needed. These demos illustrate what PingDog does — the full service runs the same checks on your schedule, from the backend, and alerts you when it confirms a state change.

Browser CORS restrictions mean the browser cannot read the response body of cross-origin hosts, only timing. PingDog's backend workers have no such restriction and collect full status codes, response bodies, and headers.

Demo 1 — Ping google.com

HTTPS reachability + latency to Google's front page.

curl -o /dev/null -s -w "status=%{http_code} latency=%{time_total}s\n" \
     https://www.google.com

Demo 2 — Ping cloudflare.com

HTTPS reachability + latency to Cloudflare's homepage.

curl -o /dev/null -s -w "status=%{http_code} latency=%{time_total}s\n" \
     https://www.cloudflare.com

Demo 3 — Ping github.com

HTTPS reachability + latency to GitHub.

curl -o /dev/null -s -w "status=%{http_code} latency=%{time_total}s\n" \
     https://github.com

Demo 4 — Catch a 404 on example.com/does-not-exist

Shows that the tool detects failures — expects HTTP 200, receives 404, reports DOWN. example.com is CORS-enabled so the exact status code is visible.

curl -o /dev/null -s -w "status=%{http_code}\n" \
     https://example.com/does-not-exist
# Expected: status=404 → PingDog would report DOWN (expect_status=200)