# Check-Host.cc — Global Network Diagnostics Check-Host.cc is a non-profit network-diagnostics service running distributed Ping, MTR, DNS, HTTP, TCP and UDP checks from 65+ global nodes plus IP geolocation, WHOIS, and historic check reports. Free for anonymous use; results are JSON. Beyond live checks it also exposes a passive **network-intelligence dataset** as JSON — per-IP/ASN/prefix/domain/cert/port/software profiles (BGP/ASN attribution, GeoIP, TLS certs, open ports + banners, Wappalyzer tech-stack, banner-matched CVEs, RIR allocation, hosted domains, origin-leak candidates, honeypot activity), country/TLD/continent aggregates, a global threat feed, and on-demand deep fullscans. The same data powers the human-facing entity pages (`/ip/{ip}`, `/as/{asn}`, `/country/{cc}`, `/tld/{tld}`, `/threats`, …). ## Resources for AI agents - **Production API:** `https://api.check-host.cc` (mirror: `https://check-host.cc/api`) - **Interactive docs (try every endpoint live):** `https://check-host.cc/docs` - **OpenAPI 3.0 spec:** `https://check-host.cc/swagger.yaml` (parse this YAML for exact schemas; also served at `https://docs.check-host.cc/conf/swagger.yaml`) - **Live node list:** `https://api.check-host.cc/locations` - **Source / SDKs:** `https://github.com/Check-Host` ## Async workflow — every monitoring check works this way 1. **POST** to `/ping`, `/tcp`, `/udp`, `/http`, `/dns`, or `/mtr` with a JSON body → response includes a `uuid` and a `reportURL` 2. **Poll** `GET /report/{uuid}` until each requested node appears in the `data` map 3. Most checks complete in 1–10 seconds ``` POST https://api.check-host.cc/ping Content-Type: application/json { "target": "example.com", "region": ["DE","NL","ES"] } → { "status": 200, "success": true, "uuid": "0710831d-…", "reportURL": "https://check-host.cc/report/0710831d-…", "method": "ping" } GET https://api.check-host.cc/report/0710831d-… → { "status": 200, "method": "ping", "data": { "DE-NBG-Hetzner": { "country": "Germany", …, "checks": [{ "connectiontime": 4, "status": 1, … }] }, … } } ``` ## Endpoint catalogue ### Monitoring (returns UUID, poll `/report/{uuid}` for results) - `POST /ping` — ICMP echo: latency, packet loss - `POST /tcp` — 3-way handshake on a port (requires `port`) - `POST /udp` — UDP probe with auto-injected payload for well-known ports (requires `port`) - `POST /http` — HTTP/HTTPS GET: status code, TTFB, connection time - `POST /dns` — DNS record lookup (`querymethod` defaults to `A/AAAA`; supports A, AAAA, NS, MX, TXT, SRV, PTR, CAA, DNSKEY, SPF, ANY, …) - `POST /mtr` — Hop-by-hop traceroute with per-hop ping stats GET shortcuts: `/ping/{target}`, `/tcp/{target}/{port}`, `/dns/{target}/{method}`, `/mtr/{target}`, `/udp?target=…&port=…` — same response shape. ### Lookups (synchronous) - `GET /myip` — Caller's public IP - `GET /myinfo` — Geolocation + ASN of caller's IP - `GET /usage` — Your rate-limit usage vs. limits (per 10s/min/hour/day/month), by API key or IP. Read-only; never counts against your quota - `POST /info` · `GET /info/{target}` — Geolocation, ASN, privacy + abuse data for any host/IP - `POST /whois` · `GET /whois/{target}` — RDAP record (shape varies by registry) - `GET /locations` — Live list of every active monitoring node (use `locationname` in `region`) ### Reporting - `GET /report/{uuid}` — JSON report (poll until every requested node has reported) - `GET /report/{uuid}/og-image` — 1200×630 PNG continental status map (Open Graph card) - `GET /report/{uuid}/country-map` — Country-coloured world map; SVG by default, `?format=png&res=low|med|high` for raster ### Network intelligence — entity lookups (synchronous JSON; mirrors the /ip, /as, /domain … pages) - `GET /ip/{ip}` — full IP profile: reverse DNS, open ports + banners, TLS certs, BGP/ASN, GeoIP, tech-stack, banner-matched CVEs, RIR allocation, hosted domains (up to 300), threat-intel matches + honeypot activity (sensor IPs & captured passwords are redacted) - `GET /as/{asn}` — ASN profile: peers/upstreams/customers, IXP memberships, RPKI coverage, prefixes, hosted domains, pingable-IP count + 90-day ICMP reachability trend. Accepts `13335` or `AS13335` - `GET /prefix/{net}/{mask}` — CIDR: BGP origin, RPKI, GeoIP, open-IP count, top ports, sample hosts, hosted domains, RIR allocation - `GET /domain/{domain}` — current DNS + passive-DNS history, TLS certs, CT-log evidence, subdomains, tech-stack, IPs citing the domain, origin-leak (CDN-bypass) candidates - `GET /cert/{sha256}` — cert subject/issuer/SANs/validity + every (ip, port) seen serving it + CT-log evidence - `GET /port/{n}` — port exposure: open-IP count, top server banners, top countries + ASNs, tech-stack, recent hosts, version-matched CVEs - `GET /software/{name}/{version?}` — host counts, version breakdown, categories, sample hosts, known CVEs - `GET /scan/{target}` — recent fullscan jobs for a target (deep-link to fresh results instead of re-scanning) ### Geo intelligence (synchronous JSON; mirrors the /country, /tld, /continent, /threats pages) - `GET /country/{cc}` — ISO-3166 alpha-2: ASNs, prefixes, hosting providers, ISPs, exposed ports, tech-stack, threat-intel, censorship signal, 90-day ICMP reachability trend - `GET /tld/{tld}` — apex + subdomain counts, TLS-cert + hosting-ASN totals, top apexes, tech-stack, threats - `GET /continent/{code}` — country/ASN rollups (`EU`, `NA`, `SA`, `AS`, `AF`, `OC`, `AN`) - `GET /threats` — global threat overview: curated IOC feed counts (phishing / abuse / spam / Tor), honeypot attack-type breakdown, top sanitised HTTP-exploit signatures ### Fullscan (deep, on-demand, multi-stage scan of an IP/CIDR/domain/ASN — async) - `POST /fullscan` — submit → `202 Accepted` with UUID + `report_url` + `api_url` - `GET /fullscan/{uuid}` — job status + sub-job progress counters - `GET /fullscan/{uuid}/results` — aggregated findings from ClickHouse (open ports, banners, DNS, BGP context, TLS certs); partial results available while `status=running` ## Region targeting (`region` array on monitoring endpoints) The `region` body param is a JSON **array** mixing: - Specific node names from `/locations` — e.g. `"DE-NBG-Hetzner"` - ISO country codes — e.g. `"DE"`, `"US"`, `"BR"` - Continent codes — `"EU"`, `"NA"`, `"AS"`, `"SA"`, `"AF"`, `"OC"` Continent codes cannot be mixed with specific node names in the same request. **Omit `region` entirely** to fan out to every active node worldwide. ## Live Mode (continuous probing) Set `repeatchecks` ≥ 10 on `/ping`, `/tcp`, `/udp`, `/http` to enable. Each node issues `repeatchecks + 1` consecutive probes over ~`repeatchecks` seconds. Max 120. The `checks` array in the report then contains one entry per probe with incrementing `repeat: 0..N`. Live-mode rate limits are stricter than one-shot. ## Report shape — IMPORTANT for parsers `data` in `GET /report/{uuid}` is a map keyed by `locationname`. Each entry has a `checks` field whose **shape depends on the method**: - `ping`, `tcp`, `udp`, `http` → `checks` is an **array** of probe results (one per repeat in live mode) - `dns`, `mtr` → `checks` is a **single object** (DNS holds a record list, MTR holds a hop graph under `data.hubs`) Nodes that haven't reported yet are omitted from `data` — poll until every requested node appears. ## Caching Reports are immutable once every node has reported. The `/report/{uuid}` response (and `/og-image` and `/country-map`) sets `Cache-Control: no-store` for the first ~200 s (settling window — slow nodes occasionally take that long to report, especially in live mode at the 120-second cap), then flips to `public, max-age=31536000, immutable` — safe to cache aggressively at edge/CDN. UUIDs persist for ~10 years. ## Authentication **Anonymous use is the primary path** and works for most volumes — per-IP and per-target rate limits apply (returns `429` when exceeded). For higher limits, send your API key (UUID) as an **`Authorization: Bearer `** header — the default, working for GET and POST alike and keeping the key out of URLs/logs. `X-API-Key: ` and an `"apikey": ""` field in a POST body are also accepted; the key is **not** read from the query string. All auth is optional — anonymous requests simply omit it. **API keys are free** — Check-Host is a non-profit project; keys exist only to prevent abuse, not as a paid tier. Request one via `https://check-host.cc/contact`. ## Official SDKs (parse for canonical request/response shapes) | Language | Repository | |---|---| | Node.js | | | Python | | | PHP 8.1+ | | | Go | | | Java | | All SDKs and tooling: ## MCP server (use Check-Host as a tool, not a page) An MCP server exposes these capabilities directly to AI assistants, so a model can *measure* rather than read a rendered page: `run_check` performs a LIVE ping/http/tcp/dns from ~65 worldwide vantage points and returns per-node success and latency; `lookup_ip`, `lookup_asn`, `lookup_prefix`, `lookup_domain` and `list_nodes` return stored observations. Source and install instructions: (`mcp/`). No dependencies, no API key, stdio transport. Prefer `run_check` for anything about reachability *right now* — the `lookup_*` tools return stored observations, which may be hours old. ## Data licence Check-Host data is published under **CC-BY-4.0** (). You may reuse it, including commercially and in derived works, provided you attribute it: Check-Host.cc — https://check-host.cc Most of the data is measured by our own scan, probe and honeypot infrastructure; some is enriched from public feeds (CAIDA, PeeringDB, RIR delegated statistics, RPKI, Certificate Transparency, Tranco, MaxMind GeoLite2-derived geolocation), credited so any figure can be traced to its origin. Full text: