Browse the docs

Monitors

Create checks of six kinds, read their results, pause them, and set the rules that drive components.

Types are http, tcp, ping, dns, ssl and heartbeat. Targets are validated and normalised at write time: URLs for http and ssl, host:port for tcp, a bare hostname for ping and dns, nothing for heartbeat. Targets that resolve to private networks are refused. Intervals are clamped to the plan's floor. See the monitors guide.

List monitors

GET/user/monitors

Every monitor in the workspace with its rules.

Needs the dashboard.read permission, or an API key with the matching scope.

Query parameters

workspace_idintegerrequired
The workspace to read from.
Request
curl "https://api.statusbee.co/user/monitors?workspace_id=5" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "rows": [
      {
        "id": 8,
        "workspace_id": 5,
        "org_id": 5,
        "type": "http",
        "name": "Checkout API",
        "target": "https://api.acme.cloud/checkout/health",
        "method": "GET",
        "headers": null,
        "body": null,
        "assertions": [
          {
            "kind": "status_code",
            "value": 200
          },
          {
            "kind": "latency_lt",
            "value": 1500
          }
        ],
        "interval_s": 60,
        "timeout_ms": 10000,
        "fail_threshold": 2,
        "recovery_threshold": 2,
        "regions": [
          "primary"
        ],
        "current_state": "up",
        "consecutive_fails": 0,
        "consecutive_passes": 14,
        "last_checked_at": "2026-09-14T09:02:11.000Z",
        "paused_at": null,
        "heartbeat_token": null,
        "ssl_expires_at": null,
        "next_run_at": "2026-09-14T09:02:11.000Z",
        "created_at": "2026-09-14T09:02:11.000Z",
        "updated_at": "2026-09-14T09:02:11.000Z",
        "rules": [
          {
            "id": 3,
            "monitor_id": 8,
            "workspace_id": 5,
            "org_id": 5,
            "component_id": 21,
            "set_component_status": "major_outage",
            "auto_incident": "draft",
            "incident_template_id": null
          }
        ]
      }
    ]
  }
}

Create a monitor

POST/user/monitors

Counts against the plan's monitors limit. The first check runs straight away. A heartbeat monitor's response includes heartbeat_url.

Needs the monitors.manage permission, or an API key with the matching scope.

Body

workspace_idintegerrequired
typestringrequired
http, tcp, ping, dns, ssl or heartbeat.
namestringrequired
Up to 100 characters.
targetstring
Required for every type except heartbeat. Format depends on the type.
interval_sintegerdefault 60
Seconds between checks, 30 to 86400. Raised to the plan's floor if lower.
timeout_msintegerdefault 10000
1000 to 60000.
fail_thresholdintegerdefault 2
Consecutive failures before down, 1 to 10.
recovery_thresholdintegerdefault 2
Consecutive passes before up, 1 to 10.
assertionsarray
HTTP only. [{ kind, value }] with kind status_code (number), latency_lt (ms) or body_contains (string).
methodstringdefault GET
HTTP only.
headersobject
HTTP only. Request headers to send.
bodystring
HTTP only. Request body, up to 10000 characters.
Request
curl -X POST "https://api.statusbee.co/user/monitors" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 5,
  "type": "http",
  "name": "Checkout API",
  "target": "https://api.acme.cloud/checkout/health",
  "interval_s": 60,
  "assertions": [
    {
      "kind": "status_code",
      "value": 200
    },
    {
      "kind": "latency_lt",
      "value": 1500
    }
  ]
}'
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 8,
    "workspace_id": 5,
    "org_id": 5,
    "type": "http",
    "name": "Checkout API",
    "target": "https://api.acme.cloud/checkout/health",
    "method": "GET",
    "headers": null,
    "body": null,
    "assertions": [
      {
        "kind": "status_code",
        "value": 200
      },
      {
        "kind": "latency_lt",
        "value": 1500
      }
    ],
    "interval_s": 60,
    "timeout_ms": 10000,
    "fail_threshold": 2,
    "recovery_threshold": 2,
    "regions": [
      "primary"
    ],
    "current_state": "pending",
    "consecutive_fails": 0,
    "consecutive_passes": 0,
    "last_checked_at": null,
    "paused_at": null,
    "heartbeat_token": null,
    "ssl_expires_at": null,
    "next_run_at": "2026-09-14T09:02:11.000Z",
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}

Get a monitor

GET/user/monitors/:id

Needs the dashboard.read permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Monitor id.
Request
curl "https://api.statusbee.co/user/monitors/3" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "monitor": {
      "id": 3,
      "workspace_id": 5,
      "org_id": 5,
      "type": "heartbeat",
      "name": "Nightly backup job",
      "target": null,
      "method": "GET",
      "headers": null,
      "body": null,
      "assertions": null,
      "interval_s": 86400,
      "timeout_ms": 10000,
      "fail_threshold": 2,
      "recovery_threshold": 2,
      "regions": [
        "primary"
      ],
      "current_state": "down",
      "consecutive_fails": 2,
      "consecutive_passes": 0,
      "last_checked_at": "2026-09-14T09:02:11.000Z",
      "paused_at": null,
      "heartbeat_token": "hb_9f2c…",
      "ssl_expires_at": null,
      "next_run_at": "2026-09-14T09:02:11.000Z",
      "created_at": "2026-09-14T09:02:11.000Z",
      "updated_at": "2026-09-14T09:02:11.000Z",
      "heartbeat_url": "https://api.statusbee.co/heartbeats/hb_9f2c…"
    },
    "rules": []
  }
}

List checks

GET/user/monitors/:id/checks

Recent results, newest first. Raw checks are kept for 30 days.

Needs the dashboard.read permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Monitor id.

Query parameters

limitintegerdefault 100
Up to 500.
fromstring
ISO 8601 lower bound on checked_at.
tostring
ISO 8601 upper bound.
Request
curl "https://api.statusbee.co/user/monitors/8/checks?limit=2" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "rows": [
      {
        "id": 88120,
        "monitor_id": 8,
        "region": "primary",
        "ok": true,
        "latency_ms": 182,
        "error": null,
        "meta": null,
        "checked_at": "2026-09-14T09:02:11.000Z"
      },
      {
        "id": 88119,
        "monitor_id": 8,
        "region": "primary",
        "ok": false,
        "latency_ms": 1840,
        "error": "HTTP 503",
        "meta": null,
        "checked_at": "2026-09-14T09:01:11.000Z"
      }
    ]
  }
}

Update a monitor

PATCH/user/monitors/:id

Any field from create. Changing type or target re-validates the target.

Needs the monitors.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Monitor id.
Request
curl -X PATCH "https://api.statusbee.co/user/monitors/8" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "interval_s": 30,
  "fail_threshold": 3
}'
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 8,
    "workspace_id": 5,
    "org_id": 5,
    "type": "http",
    "name": "Checkout API",
    "target": "https://api.acme.cloud/checkout/health",
    "method": "GET",
    "headers": null,
    "body": null,
    "assertions": [
      {
        "kind": "status_code",
        "value": 200
      },
      {
        "kind": "latency_lt",
        "value": 1500
      }
    ],
    "interval_s": 30,
    "timeout_ms": 10000,
    "fail_threshold": 3,
    "recovery_threshold": 2,
    "regions": [
      "primary"
    ],
    "current_state": "up",
    "consecutive_fails": 0,
    "consecutive_passes": 14,
    "last_checked_at": "2026-09-14T09:02:11.000Z",
    "paused_at": null,
    "heartbeat_token": null,
    "ssl_expires_at": null,
    "next_run_at": "2026-09-14T09:02:11.000Z",
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}

Pause a monitor

POST/user/monitors/:id/pause

Needs the monitors.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Monitor id.
Request
curl -X POST "https://api.statusbee.co/user/monitors/8/pause" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 8,
    "workspace_id": 5,
    "org_id": 5,
    "type": "http",
    "name": "Checkout API",
    "target": "https://api.acme.cloud/checkout/health",
    "method": "GET",
    "headers": null,
    "body": null,
    "assertions": [
      {
        "kind": "status_code",
        "value": 200
      },
      {
        "kind": "latency_lt",
        "value": 1500
      }
    ],
    "interval_s": 60,
    "timeout_ms": 10000,
    "fail_threshold": 2,
    "recovery_threshold": 2,
    "regions": [
      "primary"
    ],
    "current_state": "paused",
    "consecutive_fails": 0,
    "consecutive_passes": 14,
    "last_checked_at": "2026-09-14T09:02:11.000Z",
    "paused_at": "2026-09-14T09:02:11.000Z",
    "heartbeat_token": null,
    "ssl_expires_at": null,
    "next_run_at": "2026-09-14T09:02:11.000Z",
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}

Resume a monitor

POST/user/monitors/:id/resume

Resets the counters and schedules a check immediately.

Needs the monitors.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Monitor id.
Request
curl -X POST "https://api.statusbee.co/user/monitors/8/resume" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 8,
    "workspace_id": 5,
    "org_id": 5,
    "type": "http",
    "name": "Checkout API",
    "target": "https://api.acme.cloud/checkout/health",
    "method": "GET",
    "headers": null,
    "body": null,
    "assertions": [
      {
        "kind": "status_code",
        "value": 200
      },
      {
        "kind": "latency_lt",
        "value": 1500
      }
    ],
    "interval_s": 60,
    "timeout_ms": 10000,
    "fail_threshold": 2,
    "recovery_threshold": 2,
    "regions": [
      "primary"
    ],
    "current_state": "pending",
    "consecutive_fails": 0,
    "consecutive_passes": 0,
    "last_checked_at": "2026-09-14T09:02:11.000Z",
    "paused_at": null,
    "heartbeat_token": null,
    "ssl_expires_at": null,
    "next_run_at": "2026-09-14T09:02:11.000Z",
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}

Delete a monitor

DELETE/user/monitors/:id

Needs the monitors.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Monitor id.
Request
curl -X DELETE "https://api.statusbee.co/user/monitors/8" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "deleted": 1
  }
}

Replace the rules

PUT/user/monitors/:id/rules

Replaces the whole rule set. Each rule points at a component in the workspace and says what a state change does. See Rules and automatic incidents.

Needs the monitors.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Monitor id.

Body

rulesarrayrequired
[{ component_id, set_component_status?, auto_incident?, incident_template_id? }]. An empty array removes every rule.
rules[].component_idintegerrequired
A component in the same workspace.
rules[].set_component_statusstringdefault major_outage
Status on failure.
rules[].auto_incidentstringdefault draft
none, draft or publish.
rules[].incident_template_idinteger
A message template for the incident's wording.
Request
curl -X PUT "https://api.statusbee.co/user/monitors/8/rules" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": [
    {
      "component_id": 21,
      "set_component_status": "major_outage",
      "auto_incident": "publish",
      "incident_template_id": 4
    }
  ]
}'
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "rows": [
      {
        "id": 3,
        "monitor_id": 8,
        "workspace_id": 5,
        "org_id": 5,
        "component_id": 21,
        "set_component_status": "major_outage",
        "auto_incident": "publish",
        "incident_template_id": 4
      }
    ]
  }
}