Uptime Metrics

The uptime metrics endpoints give you raw performance data for each monitor type -- timing breakdowns for HTTP, ping response times for ICMP, and connection metrics for TCP. Each monitor type has its own dedicated endpoint.

You'll need a monitor ID for these endpoints, and all three share the same query parameters.

Example request:

$ OHDEAR_TOKEN="your API token"
$ curl "https://ohdear.app/api/monitors/1/http-uptime-metrics?filter[start]=20240419132501&filter[end]=20240420132501&filter[group_by]=minute" \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

All endpoints below follow the same authentication pattern.

Shared query parameters #

All three uptime metrics endpoints accept the same query parameters:

Query parameters:

• filter[start] (string, required) -- start of the period in YmdHis format, in UTC (e.g., 20240419132501)
• filter[end] (string, required) -- end of the period in YmdHis format, in UTC
• filter[group_by] (string, optional) -- how to aggregate the data. Possible values: minute, hour, day, week, month. Defaults to minute

Metrics per minute are stored for roughly 14 days, per hour for a couple of weeks, and per day indefinitely.

All date fields in the response are in UTC. If there are no metrics in the requested period, you'll receive an empty data array.

HTTP uptime metrics #

GET /api/monitors/{monitorId}/http-uptime-metrics

Returns detailed timing data for HTTP website monitors (type: "http").

Here's what a single metric entry looks like:

{
  "data": [
    {
      "dns_time_in_seconds": 0.001399,
      "tcp_time_in_seconds": 0.01651,
      "ssl_handshake_time_in_seconds": 0.053852,
      "remote_server_processing_time_in_seconds": 0.021595,
      "download_time_in_seconds": 0.000535,
      "total_time_in_seconds": 0.093891,
      "curl": {
        "namelookup_time": 0.001399,
        "connect_time": 0.017909,
        "appconnect_time": 0.071761,
        "starttransfer_time": 0.093356,
        "pretransfer_time": 0.071864,
        "redirect_time": 0,
        "total_time": 0.093891,
        "header_size": 1261,
        "size_download": 12814,
        "speed_download": 137784
      },
      "date": "2024-04-19 13:25:00"
    },
    "..."
  ]
}

The timing fields represent each phase of the request:

• dns_time_in_seconds: time to resolve the domain name to an IP address via DNS
• tcp_time_in_seconds: time for the TCP three-way handshake
• ssl_handshake_time_in_seconds: time for the TLS handshake (cipher negotiation and encryption)
• remote_server_processing_time_in_seconds: time the server spent processing the request before sending the first byte
• download_time_in_seconds: time to download the response body
• total_time_in_seconds: complete request duration from start to finish

The curl object contains raw values from curl. All timing values are in seconds -- multiply by 1,000 to get milliseconds (e.g., 0.0429 = 42.9ms).

Ping uptime metrics #

GET /api/monitors/{monitorId}/ping-uptime-metrics

Returns ICMP ping response data for ping monitors (type: "ping").

Here's what the response looks like:

{
  "data": [
    {
      "minimum_time_in_ms": 12.5,
      "maximum_time_in_ms": 45.2,
      "average_time_in_ms": 28.7,
      "packet_loss_percentage": 0.0,
      "uptime_percentage": 100.0,
      "downtime_percentage": 0.0,
      "uptime_seconds": 60,
      "downtime_seconds": 0,
      "date": "2024-04-19 13:25:00"
    },
    "..."
  ]
}

• minimum_time_in_ms: fastest ping response time in the period
• maximum_time_in_ms: slowest ping response time in the period
• average_time_in_ms: average ping response time in the period
• packet_loss_percentage: percentage of ping packets that were lost
• uptime_percentage / downtime_percentage: percentage of time the host was reachable or unreachable
• uptime_seconds / downtime_seconds: total seconds the host was reachable or unreachable

TCP uptime metrics #

GET /api/monitors/{monitorId}/tcp-uptime-metrics

Returns TCP connection data for TCP port monitors (type: "tcp").

Here's what the response looks like:

{
  "data": [
    {
      "time_to_connect_in_ms": 15.3,
      "uptime_percentage": 100.0,
      "downtime_percentage": 0.0,
      "uptime_seconds": 60,
      "downtime_seconds": 0,
      "date": "2024-04-19 13:25:00"
    },
    "..."
  ]
}

• time_to_connect_in_ms: time to establish the TCP connection
• uptime_percentage / downtime_percentage: percentage of time the port was accessible or inaccessible
• uptime_seconds / downtime_seconds: total seconds the port was accessible or inaccessible