API Reference

Public status, readiness, history, and incident record endpoints for downdetector.com.

Overview

The API publishes the latest check result, recent history, and incident records through /api/v1/* endpoints.

Public reads do not require an account. Accounts only add API keys, email alerts, and security settings.

Status Trust and Readiness

Decision rule: treat status as current truth only when monitor.trusted is true and monitor.resultFreshness is "current".

Humans can verify on the homepage live status panel; trust it only when no freshness warning is present.

/api/v1/status is for public displays and returns the latest observed verdict plus monitor trust metadata.
A 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.
Notification-provider failures are logged separately and do not make the checker unhealthy when probe results and any incident state changes were persisted.

Incident semantics

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 a boolean review flag. falsePositiveReason is an optional operator note when the flag is set. Reviewed as false alarm means falsePositive is true; the UI may show the reason when falsePositiveReason is present.
Incident record detail and update feeds expand timelines beyond list summaries on /api/v1/incidents.

Public Endpoints

GET/api/v1/status

Returns 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".

Example Response

{
  "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
  }
}

targetstringThe URL being checked, fixed to https://downdetector.com.

statusstringLast observed target verdict: "up", "down", or "checking". This may remain the previous verdict when the monitor is untrusted.

checkedAtstringISO 8601 timestamp of when the status was determined.

lastCheckAtnumberUnix timestamp in milliseconds for the last check.

nextCheckAtnumberAdvisory Unix timestamp in milliseconds for the next scheduled check, ornull before the first completed check.

intervalMsnumberBackend monitor cadence in milliseconds.

monitor.trustedbooleantrue 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.

monitor.resultFreshnessstring"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.runningbooleanWhether the status checker process is currently running.

monitor.stalebooleanWhether the checker is behind its expected cadence.

monitor.staleAfterMsnumberMilliseconds after the last completed run before the checker is considered stale.

monitor.lastRunCompletedAtnumber | nullUnix timestamp in milliseconds for the last completed checker run.

monitor.alertobject | nullSafe public checker-health alert metadata with sanitized messages. When non-null, clients should show caution instead of presenting the cached verdict as fully trusted.

Monitor Alert Codes

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.

View raw live response

GET/api/v1/health

Returns 200 when the API process is up. This is a liveness check only; it does not validate MongoDB, monitor freshness, or persisted snapshot evidence.

Example Response

{
  "status": "ok",
  "service": "api",
  "uptimeSeconds": 123
}

View raw live response

GET/api/v1/ready

Returns 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.

Ready Response

{
  "status": "ready",
  "service": "api",
  "checks": {
    "mongodb": "up",
    "monitor": "up"
  },
  "monitor": {
    "lastRunCompletedAt": 1771189200000,
    "intervalMs": 30000,
    "staleAfterMs": 90000,
    "alert": null
  }
}

Not Ready Response

{
  "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."
  }
}

statusstring"ready" with HTTP 200, or "not_ready" with HTTP 503.

checks.mongodbstringMongoDB dependency state. Status history and incident state reads depend on this being "up".

checks.monitorstringChecker readiness state. "down" means clients should not treat the cached status verdict as current truth.

monitor.lastPersistenceErrorstring | nullGeneric public persistence-health message. Raw database, environment, and credential details are not exposed.

View raw live response

GET/api/v1/history?hours=24&binMinutes=15

Returns binned status counts for timelines. Query params: hours(default 24, max 168) and binMinutes.

Example Response

{
  "target": "https://downdetector.com",
  "from": "2026-02-14T21:00:00.000Z",
  "to": "2026-02-15T21:00:00.000Z",
  "binMinutes": 15,
  "samples": 2880,
  "uptime": { "up": 2879, "down": 1, "total": 2880, "pct": 0.99965 },
  "bins": [
    { "start": "2026-02-15T20:45:00.000Z", "up": 30, "down": 0, "total": 30, "status": "up" }
  ]
}

GET/api/v1/incidents?limit=50

Returns recent incident records (default limit 50, max 200). List items include falsePositive and falsePositiveReason. For one incident record, use /api/v1/incidents/:id.

Example Response

{
  "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
    }
  ]
}

GET/api/v1/incidents/:id

Returns one incident record by id, including target, state, timing, trigger, review flags, and detail-only review metadata.

Example Response

{
  "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": "DownDetector Monitor"
  }
}

GET/api/v1/incidents/:id/updates

Returns the append-only incident record update feed for timeline expansion beyond list summaries. Updates may include a postmortem after resolution.

Example Response

{
  "updates": [
    {
      "id": "65cfdc2a2f2d2f3d2f2d2f2e",
      "kind": "investigating",
      "body": "Monitoring repeated probe failures.",
      "createdBy": "DownDetector Monitor",
      "createdAt": "2026-02-15T20:11:00.000Z"
    }
  ]
}

GET/api/v1/history/probes?hours=1&limit=50

Returns recent raw probe snapshots for the monitored target.

Optional Account Features

Free accounts can create up to three API keys, subscribe to incident email alerts, and manage security settings. Public reads still work without login.

API keys are managed from Account Settings.
Authenticated API key management uses 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.
Alert preferences are managed under Account Settings.
Existing accounts can sign in at /login, and new accounts remain free when signup is open.

Usage Notes

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.