Incidents API

Track, manage, and comment on incidents when monitors detect issues.

Incidents are automatically created when a monitor fails its checks according to the configured fail threshold. Each incident tracks the downtime period, affected regions, and failure reasons.

Note: Incidents are read-only except for adding comments. They are automatically resolved when the monitor returns to an up state.

Incident Lifecycle

Created

When fail threshold reached

Ongoing

Tracks downtime duration

Resolved

When monitor recovers

Incidents provide a complete history of downtime events with detailed check results from all monitoring regions, helping you understand and diagnose issues.

GET/api/incidents

Retrieve a paginated list of incidents with optional filtering.

Query Parameters

Name	Type	Required	Description
page	`integer`	No	Page number for paginationDefault: `1`Example: `2`
per_page	`integer`	No	Items per page (max 100)Default: `20`Example: `50`
monitor_id	`string`	No	Filter by specific monitor IDExample: `507f1f77bcf86cd799439011`
resolved	`boolean`	No	Filter by resolution statusExample: `false`

Example Request

curl -X GET "https://api.uptime-monitor.io/api/incidents?resolved=false&per_page=10" \
  -H "Authorization: Bearer um_xxxx"

Example Response

{
  "status": "ok",
  "data": {
    "incidents": [
      {
        "id": "507f1f77bcf86cd799439011",
        "is_resolved": false,
        "started_at": 1640995200,
        "duration": "Ongoing",
        "user_comment": "",
        "reason": "Connection timeout",
        "check_results": {
          "us-east-1": {
            "checker_ip": "54.123.45.67",
            "ts": 1640995200,
            "time": 30000,
            "status": "down",
            "error": {
              "reason": "Connection timeout",
              "http_check_details": null
            },
            "timestamp": 1640995200
          }
        }
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 45,
      "total_pages": 5,
      "has_next": true,
      "has_prev": false
    }
  }
}

GET/api/incidents/:id

Retrieve detailed information about a specific incident.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Incident IDExample: `507f1f77bcf86cd799439011`

Example Request

curl -X GET https://api.uptime-monitor.io/api/incidents/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer um_xxxx"

Example Response

{
  "status": "ok",
  "data": {
    "incident": {
      "id": "507f1f77bcf86cd799439011",
      "is_resolved": true,
      "started_at": 1640995200,
      "duration": "2h 15m",
      "user_comment": "Network issue at datacenter, resolved after provider fix",
      "reason": "503 Service Unavailable",
      "check_results": {
        "us-east-1": {
          "checker_ip": "54.123.45.67",
          "ts": 1640995200,
          "time": 523,
          "status": "down",
          "error": {
            "reason": "503 Service Unavailable",
            "http_check_details": {
              "status_code": 503,
              "headers": {
                "server": "nginx/1.21.0"
              }
            }
          },
          "timestamp": 1640995200
        }
      }
    }
  }
}

Error Responses

404

Incident not found

400

Invalid incident ID format

PATCH/api/incidents/:id/comment

Add or update a comment on an incident for post-mortem documentation.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Incident IDExample: `507f1f77bcf86cd799439011`

Body Parameters

Name	Type	Required	Description
comment	`string`	Yes	Comment text for the incidentExample: `Database server ran out of memory due to traffic spike`

Example Request

curl -X PATCH https://api.uptime-monitor.io/api/incidents/507f1f77bcf86cd799439011/comment \
  -H "Authorization: Bearer um_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Database server ran out of memory due to traffic spike. Increased memory allocation and implemented better caching."
  }'

Example Response

{
  "status": "ok",
  "data": {
    "incident": {
      "id": "507f1f77bcf86cd799439011",
      "is_resolved": true,
      "started_at": 1640995200,
      "duration": "2h 15m",
      "user_comment": "Database server ran out of memory due to traffic spike. Increased memory allocation and implemented better caching.",
      "reason": "503 Service Unavailable",
      "check_results": {
        "us-east-1": {
          "checker_ip": "54.123.45.67",
          "ts": 1640995200,
          "time": 500,
          "status": "down",
          "error": {
            "reason": "503 Service Unavailable",
            "http_check_details": {
              "status_code": 503,
              "headers": {
                "server": "nginx/1.21.0"
              }
            }
          },
          "timestamp": 1640995200
        }
      }
    }
  }
}

Error Responses

404

Incident not found

400

Invalid incident ID format

Check Result Structure

Each region check result contains diagnostic information:

Check Result Fields

{
  "checker_ip": "54.123.45.67",     // IP address of the checker
  "ts": 1640995200,                 // Timestamp of the check (Unix)
  "time": 523,                      // Response time in milliseconds
  "status": "down",                 // Check status: up, down, or degraded
  "error": {                        // Present only when status is not "up"
    "reason": "Connection timeout",  // Human-readable error description
    "http_check_details": {         // Additional details for HTTP checks
      "status_code": 503,
      "headers": {
        "server": "nginx/1.21.0"
      }
    }
  },
  "timestamp": 1640995200           // Unix timestamp (same as ts)
}

← Monitors API Status Pages API →