Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Uptime API

4 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/environments/{environmentId}/uptime

Uptime of every service of an environment

Each service with its state, its availability over the last 30 UTC days and 30 daily points. Needs projects:read.

ParameterInTypeDescription
environmentIdrequiredpathstring
Response 200 · OK · application/json
EnvironmentUptimeOutputBody
  • EnvironmentService[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/uptime

Uptime of a service

Current state (up, degraded, down, maintenance, paused, unknown) with when it began, the last check, last error and latency; consecutiveFailures and failureThreshold show a failure streak that is not an outage yet; availability over 24 hours, 7, 30 and 90 days (up + degraded) / (checks - maintenance), null without data; a series of the range (60 minute cells for 1h, hourly points for 24h and 7d, UTC days for 30d and 90d; every bucket is present, with checks 0 where there was no data) and the 20 most recent outages. Checks come from the service's server every 30 seconds. Needs projects:read.

ParameterInTypeDescription
serviceIdrequiredpathstring
rangequeryenum: 1h | 24h | 7d | 30d | 90dWindow of the series: 60 minute cells for 1h, hourly points for 24h and 7d, UTC days for 30d and 90d.
Response 200 · OK · application/json
ServiceReport
  • AvailabilityViewrequired
  • consecutiveFailuresinteger (int64)required
    Failed checks in a row right now. An outage opens when it reaches failureThreshold (during a deployment the count stays 0).
  • failureThresholdinteger (int64)required
    The service's effective failure threshold (the default 3 without a monitor).
  • granularityenum: minute | hour | dayrequired
    Width of the series buckets: minutes for 1h, hours for 24h and 7d, UTC days for 30d and 90d.
  • UptimeIncidentView[] | nullrequired
    The most recent 20, newest first.
  • lastCheckAtstring (date-time) | nullrequired
  • lastErrorstringrequired
    What the last failing check reported; empty while it passes.
  • lastOkAtstring (date-time) | nullrequired
  • latencyMsinteger (int64) | nullrequired
    Latency of the last passing check that measured one.
  • MonitorViewrequired
  • rangeenum: 1h | 24h | 7d | 30d | 90drequired
  • UptimePoint[] | nullrequired
    Oldest first, ending with the running bucket; every bucket of the range is present, with checks 0 where there was no data. 1h has 60 minute cells, 24h 24 hours, 7d 168 hours, 30d 30 days, 90d 90 days.
  • serviceIdstringrequired
  • sincestring (date-time) | nullrequired
    When the state was entered; null before the first check.
  • stateenum: up | degraded | down | maintenance | paused | unknownrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/uptime-monitor

Get a service's uptime monitor settings

Whether the service is probed, whether outages alert, and how many failed or passing checks open and end an outage. A service without settings is monitored with the defaults (3 and 2). Needs projects:read.

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 200 · OK · application/json
MonitorView
  • alertsbooleanrequired
    Send uptime.down and uptime.up notifications for outages of this service. Outages are recorded either way.
  • enabledbooleanrequired
    Probe the service. When off, agents stop probing it and its state is paused.
  • failureThresholdinteger (int64)required
    Consecutive failed checks (30 s apart) that open an outage.
  • recoveryThresholdinteger (int64)required
    Consecutive passing checks that end it.
  • reminderMinutesinteger (int64)required
    While an outage lasts, send uptime.down again every this many minutes (counted from the last alert). 0 = never. Needs alerts on; not sent during maintenance.
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/services/{serviceId}/uptime-monitor

Set a service's uptime monitor settings

Replaces the settings. Takes effect without a deployment: the server's agent stops or resumes probing the service within seconds. Switching monitoring off pauses the service and closes its open outage without a recovery notice. Needs the admin scope (workspace owner or admin). Audited as uptime_monitor.update.

ParameterInTypeDescription
serviceIdrequiredpathstring
Request body · application/json · required
MonitorView
  • alertsbooleanrequired
    Send uptime.down and uptime.up notifications for outages of this service. Outages are recorded either way.
  • enabledbooleanrequired
    Probe the service. When off, agents stop probing it and its state is paused.
  • failureThresholdinteger (int64)required
    Consecutive failed checks (30 s apart) that open an outage.
  • recoveryThresholdinteger (int64)required
    Consecutive passing checks that end it.
  • reminderMinutesinteger (int64)required
    While an outage lasts, send uptime.down again every this many minutes (counted from the last alert). 0 = never. Needs alerts on; not sent during maintenance.
Response 200 · OK · application/json
MonitorView
  • alertsbooleanrequired
    Send uptime.down and uptime.up notifications for outages of this service. Outages are recorded either way.
  • enabledbooleanrequired
    Probe the service. When off, agents stop probing it and its state is paused.
  • failureThresholdinteger (int64)required
    Consecutive failed checks (30 s apart) that open an outage.
  • recoveryThresholdinteger (int64)required
    Consecutive passing checks that end it.
  • reminderMinutesinteger (int64)required
    While an outage lasts, send uptime.down again every this many minutes (counted from the last alert). 0 = never. Needs alerts on; not sent during maintenance.
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.