Loading Reachability Record
The requested page will appear when its current record is ready.
Public status, readiness, history, and incident record endpoints for downdetector.com.
Machine-readable contract
The contract covers observation, history, probe, incident, health, readiness, and version reads. It does not advertise account writes or an MCP server.
The API publishes the latest check result, recent history, and incident records through /api/v1/* endpoints.
Reachability Record checks one target. It does not search other services or accept crowd outage reports, and none of its responses represent an official Downdetector status statement.
Public reads do not require an account. Optional account API keys provide a separate per-key rate identity; they do not unlock write operations on the monitored target or promise a higher default limit.
Decision rule: treat status as current truth only when monitor.trusted is true and monitor.resultFreshness is "current".
Humans can confirm the same rule on the homepage live status panel, which shows a freshness warning whenever the verdict may be stale.
/api/v1/status is for public displays and returns the latest observed verdict plus monitor trust metadata.200 status response can still be untrusted. Persistence, staleness, or internal checker health issues preserve the last observed up/down value while marking the monitor untrusted./api/v1/ready is for load balancers, deploy smoke, and ops checks. It is stricter than status: MongoDB must be reachable, the checker must have completed a recent run, and recent status snapshot evidence must be persisted.Incident records are stored event records, not the live /api/v1/status verdict. Use status for the current panel answer when monitor.trusted is true and monitor.resultFreshness is "current"; use incident endpoints for how outages were recorded, labeled, and reviewed.
consecutive_down: prefixes automated incident records opened after repeated failed checks (for example consecutive_down:3).manual: prefixes operator-opened incident records. Text after the colon is an optional review note, not a separate API field.falsePositive is the boolean review flag when that state applies; falsePositiveReason is an optional operator note when the flag is set. The UI may show the reason when falsePositiveReason is present./api/v1/incidents.404 means no matching stored incident record. A dependency or transport failure is reported as unavailable and must not be cached or presented as a missing record./api/v1/statusReturns the latest cached verdict, timestamps, monitor cadence, next scheduled check time, incident context, and a monitor trust block. Do not treat status as authoritative unless monitor.trusted is true and monitor.resultFreshness is "current".
{
"target": "https://downdetector.com",
"status": "up",
"checkedAt": "2026-02-15T21:00:00.000Z",
"lastCheckAt": 1771189200000,
"nextCheckAt": 1771189230000,
"intervalMs": 30000,
"httpStatus": 403,
"latencyMs": 312,
"error": null,
"incident": null,
"monitor": {
"trusted": true,
"resultFreshness": "current",
"running": true,
"stale": false,
"staleAfterMs": 90000,
"lastRunCompletedAt": 1771189200000,
"alert": null
}
}https://downdetector.com."up", "down", or "checking". This may remain the previous verdict when the monitor is untrusted.null before the first completed check.true only when the checker is running, has completed a check, is not stale, has no active internal or persistence health warning, and monitor.alert is null."current", "stale", or "unknown". "current" is emitted only when the public verdict is trusted; "unknown" covers non-stale trust failures such as persistence errors.monitor_stopped: checker is not running.monitor_never_completed: no completed check yet.monitor_stale: checks are behind schedule.monitor_persistence_error: recent check evidence could not be saved.monitor_internal_error: sanitized internal checker warning./api/v1/healthReturns 200 when the API process is up. This is a liveness check only; it does not validate MongoDB, monitor freshness, or persisted snapshot evidence.
{
"status": "ok",
"service": "api",
"uptimeSeconds": 123
}/api/v1/readyReturns whether the API is ready to serve trustworthy status data. It returns 200 only when MongoDB is reachable and the monitor has completed a recent check with persisted status snapshot and any incident state changes.
Persistence failures are readiness-critical and make public status metadata untrusted. Notification-provider failures are logged separately and do not make the checker unhealthy after probe results and any incident state changes were persisted.
{
"status": "ready",
"service": "api",
"checks": {
"mongodb": "up",
"monitor": "up"
},
"monitor": {
"lastRunCompletedAt": 1771189200000,
"intervalMs": 30000,
"staleAfterMs": 90000,
"alert": null
}
}{
"status": "not_ready",
"service": "api",
"checks": {
"mongodb": "up",
"monitor": "down"
},
"monitor": {
"running": true,
"stale": false,
"alert": {
"code": "monitor_persistence_error",
"level": "warning",
"message": "Status checker is unable to save recent check evidence.",
"observedAt": 1771189205000
},
"lastRunCompletedAt": 1771189200000,
"lastSuccessfulRunAt": 1771189170000,
"lastInternalError": null,
"lastPersistenceError": "Status checker is unable to save recent check evidence."
}
}"ready" with HTTP 200, or "not_ready" with HTTP 503."up"."down" means clients should not treat the cached status verdict as current truth./api/v1/history?hours=24&binMinutes=15Returns binned status counts for timelines. Query params: hours(default 24, max 168) and binMinutes.
samples is the number of observed checks, and the legacy uptime.pct field is the share of successful checks among the observed samples. Neither field claims continuous coverage between observations.
A period is down when down > 0 and down >= up; otherwise it is up. A period with no samples is unknown.
{
"target": "https://downdetector.com",
"from": "2026-02-14T21:00:00.000Z",
"to": "2026-02-15T21:00:00.000Z",
"binMinutes": 15,
"samples": 3,
"uptime": { "up": 2, "down": 1, "total": 3, "pct": 0.66667 },
"bins": [
{ "start": "2026-02-15T20:45:00.000Z", "up": 2, "down": 1, "total": 3, "status": "up" }
]
}/api/v1/incidents?limit=50Returns recent incident records (default limit 50, max 200). List items include falsePositive and falsePositiveReason. For one incident record, use /api/v1/incidents/:id.
{
"incidents": [
{
"id": "65cfdc2a2f2d2f3d2f2d2f2d",
"target": "https://downdetector.com",
"state": "resolved",
"startedAt": "2026-02-15T20:10:00.000Z",
"endedAt": "2026-02-15T20:18:00.000Z",
"trigger": "consecutive_down:3",
"falsePositive": false,
"falsePositiveReason": null
}
]
}/api/v1/incidents/:idReturns one incident record by id, including target, state, timing, trigger, review flags, and detail-only review metadata.
{
"incident": {
"id": "65cfdc2a2f2d2f3d2f2d2f2d",
"target": "https://downdetector.com",
"state": "resolved",
"startedAt": "2026-02-15T20:10:00.000Z",
"endedAt": "2026-02-15T20:18:00.000Z",
"trigger": "manual:operator review after edge-case checks",
"falsePositive": true,
"falsePositiveReason": "Target returned 403; site remained reachable.",
"falsePositiveMarkedAt": "2026-02-15T20:25:00.000Z",
"falsePositiveMarkedBy": "Monitor operator"
}
}/api/v1/incidents/:id/updatesReturns the append-only incident record update feed for timeline expansion beyond list summaries. Updates may include a postmortem after resolution.
{
"updates": [
{
"id": "65cfdc2a2f2d2f3d2f2d2f2e",
"kind": "update",
"body": "Monitoring repeated probe failures.",
"createdBy": "Monitor operator",
"createdAt": "2026-02-15T20:11:00.000Z"
}
]
}/api/v1/history/probes?hours=1&limit=50Returns recent probe snapshots with opaque region aliases and sanitized outcome labels. Internal region names, target overrides, and raw network errors are not exposed.
Free accounts can create up to three API keys, subscribe to incident email alerts, and manage security settings. Public reads still work without login.
GET /api/v1/api-keys, POST /api/v1/api-keys, and POST /api/v1/api-keys/:id/revoke. Use a Bearer access token from a signed-in session; key secret values are shown only when created.Polling every 10-30 seconds is enough for public status reads. Prefer nextCheckAt for countdowns, and refresh shortly after it instead of polling continuously.
Public endpoints are rate limited and return standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.
Public read endpoints are limited to 120 requests per minute per client. See Access & Limits for account limits.
For automation, prefer /api/v1/ready as a dependency check and use monitor.trusted plus monitor.resultFreshness to decide how confidently to display the latest cached verdict.
When the monitor is untrusted, show monitor.alert.message when present or a neutral last-check caution instead of rendering a definitive green/red answer.
An up status means the target returned an HTTP status code under 500. That includes 403 responses caused by Cloudflare bot protection because the site is still reachable in that case.