監控 API 參考

Monitors

Check the uptime of your websites, APIs, and services

Cron Monitors

Monitor your scheduled jobs via HTTP pings

欄位的可用值

監控地點

值	說明
`US_EAST_1`	北維吉尼亞
`CA_CENTRAL_1`	加拿大（蒙特婁）
`EU_CENTRAL_1`	法蘭克福
`AP_NORTHEAST_1`	東京

監控警報類型

值	說明
`INCIDENT`	事件警報
`EMAIL`	電子郵件警報
`SMS`	簡訊警報
`SLACK`	Slack 警報
`DISCORD`	Discord 警報
`MICROSOFT_TEAMS`	Microsoft Teams 警報
`PHONE_CALL`	電話通知警報
`WEBHOOK`	Webhook 警報
`GOOGLE_CHAT`	Google Chat 警報
`WHATSAPP`	WhatsApp 警報

監控狀態

值	說明
`UP`	監控運行正常
`DOWN`	監控失敗
`DEGRADED`	監控出現問題
`UNKNOWN`	無法判斷監控狀態

取得監控

你可以用這個端點查詢並瀏覽所有既有監控的清單。

端點：

GET /:page_id/monitors

查詢參數

參數	型別	預設值	說明
`page`	`number`	`1`	要取得的頁碼。
`limit`	`number`	`100`	每頁的監控數量。
`search`	`string`	`null`	用來篩選結果的搜尋字詞。
`status`	`enum`	`null`	狀態篩選（'UP'、'DOWN'、'UNKNOWN'、'DEGRADED'）。

請求範例

GET /1/monitors?limit=3&page=2&status=DOWN

回應範例

{
  "monitors": [{ "...": "monitor objects" }],
  "total": 10,
  "page": 3,
  "totalPages": 5,
  "limit": 2
}

建立監控

端點：

POST /monitors

請求範例

{
  "pageId": "page123",
  "url": "https://example.com",
  "httpMethod": "GET",
  "body": null,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer token"
  },
  "queryParams": {
    "search": "test",
    "limit": "10"
  },
  "basicAuth": {
    "username": "user",
    "password": "password"
  },
  "type": "HTTP",
  "assertions": [
    {
      "type": "STATUSCODE",
      "comparison": "EQUALS",
      "selector": null,
      "target": "200"
    }
  ],
  "alerts": ["alert-id-1", "alert-id-2"],
  "name": "Example Monitor",
  "locations": "US_EAST_1",
  "checksInterval": 300,
  "createComponent": true,
  "createMetric": true,
  "onFail": {
    "createIncident": true,
    "createOutageDuration": true,
    "publishIncident": true,
    "notifySubscribers": true
  },
  "onRecover": {
    "resolveIncident": true,
    "resolveOutageDuration": true,
    "publishIncident": true,
    "notifySubscribers": true
  }
}

回應範例

{
  "monitor": {
    "pageId": "page123",
    "url": "https://example.com",
    "httpMethod": "GET",
    "body": null,
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer token"
    },
    "queryParams": {
      "search": "test",
      "limit": "10"
    },
    "basicAuth": {
      "username": "user",
      "password": "password"
    },
    "type": "HTTP",
    "assertions": [
      {
        "id": "assertion1",
        "type": "STATUSCODE",
        "comparison": "EQUALS",
        "selector": null,
        "target": "200"
      }
    ],
    "alerts": ["alert1", "alert2"],
    "name": "Example Monitor",
    "locations": "US_EAST_1",
    "checksInterval": 300,
    "createComponent": true,
    "createMetric": true,
    "onFail": {
      "createIncident": true,
      "createOutageDuration": true,
      "publishIncident": true,
      "notifySubscribers": true
    },
    "onRecover": {
      "resolveIncident": true,
      "resolveOutageDuration": true,
      "publishIncident": true,
      "notifySubscribers": true
    },
    "createdAt": "2023-08-08T12:00:00Z",
    "updatedAt": "2023-08-08T12:00:00Z"
  },
  "message": "Monitor created successfully"
}

更新監控

端點：

PUT /monitors/:id

請求範例

{
  "url": "https://updated.com",
  "name": "Updated Monitor Name"
}

回應範例

{
  "monitor": {
    "pageId": "page123",
    "url": "https://updated.com",
    "httpMethod": "GET",
    "body": null,
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer token"
    },
    "queryParams": {
      "search": "test",
      "limit": "10"
    },
    "basicAuth": {
      "username": "user",
      "password": "password"
    },
    "type": "HTTP",
    "assertions": [
      {
        "id": "assertion1",
        "type": "STATUSCODE",
        "comparison": "EQUALS",
        "selector": null,
        "value": "200"
      }
    ],
    "alerts": ["alert1", "alert2"],
    "name": "Updated Monitor Name",
    "locations": "US_EAST_1",
    "checksInterval": 300,
    "createComponent": true,
    "createMetric": true,
    "onFail": {
      "createIncident": true,
      "createOutageDuration": true,
      "publishIncident": true,
      "notifySubscribers": true
    },
    "onRecover": {
      "resolveIncident": true,
      "resolveOutageDuration": true,
      "publishIncident": true,
      "notifySubscribers": true
    },
    "createdAt": "2023-08-08T12:00:00Z",
    "updatedAt": "2023-08-08T12:00:00Z"
  },
  "message": "Monitor updated successfully"
}

刪除監控

端點：

DELETE /monitors/:id

請求範例

DELETE /monitors/monitor-id-1

回應範例

{
  "message": "Monitor deleted successfully."
}

取得監控紀錄

端點：

GET /monitors/:id/logs

查詢參數

參數	型別	預設值	說明
`limit`	`number`	100	每頁的項目數，不能超過 1000。
`page`	`number`	1	要取得的頁碼。
`monitorId`	`string`	-	監控的 ID。
`location`	`string`	`null`	監控的地點。
`createdAt`	`string` \| `object` \| `number`	`null`	建立日期。可以是字串、數字，或含有 `gte` 與 `lte` 欄位的物件。
`isSuccessful`	`boolean`	`null`	檢查是否成功。
`isSSLCheck`	`boolean`	`null`	是否為 SSL 檢查。
`httpStatusCode`	`string`	`null`	回應的 HTTP 狀態碼。
`status`	`('UP', 'DOWN', 'UNKNOWN', 'DEGRADED')`	`null`	監控的狀態。
`dnsTime`	`string` \| `number` \| `object`	`null`	DNS 解析花費的時間。
`tcpTime`	`string` \| `number` \| `object`	`null`	TCP 連線花費的時間。
`tlsTime`	`string` \| `number` \| `object`	`null`	TLS 交握花費的時間。
`firstByteTime`	`string` \| `number` \| `object`	`null`	收到第一個位元組所花費的時間。
`downloadTime`	`string` \| `number` \| `object`	`null`	下載花費的時間。
`responseTime`	`string` \| `number` \| `object`	`null`	總回應時間。
`performanceTime`	`string` \| `number` \| `object`	`null`	效能時間。
`accessabilityScore`	`string` \| `number` \| `object`	`null`	無障礙分數。
`seoScore`	`string` \| `number` \| `object`	`null`	SEO 分數。
`bestPracticesScore`	`string` \| `number` \| `object`	`null`	最佳做法分數。
`successfulAssertions`	`string` \| `number` \| `object`	`null`	成功的判斷條件數量。
`sort`	`string`	依時間順序	用來排序的欄位。

請求範例

GET /monitors/monitor-id-1/logs?limit=100&page=1

回應範例

{
  "monitorLogs": [
    // {monitor log object},
    // {monitor log object 2}
  ],
  "total": 478,
  "page": 1,
  "totalPages": 5,
  "limit": 100
}

依 ID 執行監控檢查

端點：

GET /monitors/:id/run

查詢參數

參數	型別	預設值	說明
`location`	`'US_EAST_1', 'EU_CENTRAL_1', 'AP_NORTHEAST_1', 'AP_SOUTHEAST_2', 'CA_CENTRAL_1'`	-	監控的地點，必須是列出的值之一。
`retry`	`boolean`	`false`	是否要重試該操作。選填。
`monitorLogId`	`string`	`null`	監控紀錄的唯一識別碼。選填。

請求範例

GET /monitors/monitor-id-1/run?monitorId=abc123&location=US_EAST_1&retry=true&monitorLogId=log456

回應範例

{
  "status": "success",
  "message": "Monitor check run successfully."
}

建立監控警報

端點：

POST /monitor-alerts

請求範例

{
  "type": "EMAIL",
  "pageId": "page123",
  "recipient": "user@example.com",
  "recipientWorkspace": "workspace123",
  "whenFails": true,
  "whenRecovers": true,
  "whenDegrades": false,
  "whenSslExpires": true,
  "sslExpiresInDays": 30,
  "monitors": ["monitor1", "monitor2"],
  "metadata": "Additional information about the alert"
}

回應範例

{
  "monitor": {
    "id": "alert123",
    "siteId": "site123",
    "type": "EMAIL",
    "recipient": "user@example.com",
    "whenFails": true,
    "whenRecovers": true,
    "whenDegrades": false,
    "whenSslExpires": true,
    "sslExpiresInDays": 30,
    "monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],
    "createdAt": "2023-08-08T12:00:00Z",
    "updatedAt": "2023-08-08T12:00:00Z",
    "metadata": "Additional information about the alert"
  },
  "message": "Monitor Alert created successfully"
}

更新監控警報

端點：

PUT /monitor-alerts/:id

請求範例

{
  "type": "EMAIL",
  "monitors": ["monitor-1-id", "monitor-2-id", "monitor-3-id"]
}

回應範例

{
  "monitor": {
    "type": "EMAIL",
    "pageId": "page123",
    "recipient": "user@example.com",
    "recipientWorkspace": "workspace123",
    "whenFails": true,
    "whenRecovers": true,
    "whenDegrades": false,
    "whenSslExpires": true,
    "sslExpiresInDays": 30,
    "monitors": ["monitor-1-id", "monitor-2-id"],
    "metadata": "Additional information about the alert"
  },
  "message": "Monitor alert updated successfully."
}

取得監控警報

端點：

GET /:page_id/monitor-alerts

查詢參數

參數	型別	預設值	說明
`limit`	`number`	100	每頁的項目數。
`page`	`number`	1	要取得的頁碼。

請求範例

GET /1/monitor-alerts?limit=2&page=3

回應範例

{
  "monitorAlerts": [
    {...monitor alert objects}
  ],
  "total": 27,
  "page": 3,
  "totalPages": 14,
  "limit": 2
}

刪除監控警報

端點：

DELETE /monitor-alerts/:id

請求範例

DELETE /monitor-alerts/alert-id-1

回應範例

{
  "message": "Monitor alert deleted successfully."
}

建立監控群組

端點：

POST /monitors-groups

請求範例

{
  "pageId": "page123",
  "name": "Example Name",
  "childId": "child456"
}

回應範例

{
  "monitor": {
    "id": "group123",
    "name": "Example Name",
    "siteId": "site123",
    "collapsed": false,
    "monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],
    "groupId": "parentGroup123",
    "children": [
      { "id": "childGroup1", "name": "Child Group 1" },
      { "id": "childGroup2", "name": "Child Group 2" }
    ],
    "order": 1,
    "createdAt": "2023-08-08T12:00:00Z",
    "updatedAt": "2023-08-08T12:00:00Z",
    "parents": ["parent1", "parent2"],
    "componentId": "component123"
  },
  "message": "Monitor group created successfully."
}

更新監控群組

端點：

PUT /monitors-groups/:id

請求範例

{
  "name": "Updated Monitor Group Name"
}

回應範例

{
  "monitor": {
    "id": "group123",
    "name": "Updated Monitor Group Name",
    "siteId": "site123",
    "collapsed": true,
    "monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],
    "groupId": "parentGroup123",
    "children": [
      { "id": "childGroup1", "name": "Child Group 1" },
      { "id": "childGroup2", "name": "Child Group 2" }
    ],
    "order": 1,
    "createdAt": "2023-08-08T12:00:00Z",
    "updatedAt": "2023-08-08T12:00:00Z",
    "parents": ["parent1", "parent2"],
    "componentId": "component123"
  },
  "message": "Monitor group updated successfully."
}

刪除監控群組

端點：

DELETE /monitors-groups/:id

請求範例

DELETE /monitors-groups/group-id-1

回應範例

{
  "message": "Monitor group deleted successfully."
}

把監控加入群組

端點：

POST /monitors-groups/:id/monitors

請求範例

{
  "monitors": ["monitor1", "monitor2", "monitor3"]
}

回應範例

{
  "message": "Monitors added to the group successfully."
}

執行監控群組檢查

端點：

GET /monitors-groups/:id/run

查詢參數

參數	型別	預設值	說明
`location`	`'US_EAST_1', 'EU_CENTRAL_1', 'AP_NORTHEAST_1', 'AP_SOUTHEAST_2', 'CA_CENTRAL_1'`	-	監控的地點，必須是列出的值之一。
`retry`	`boolean`	`false`	是否要重試該操作。選填。
`monitorLogId`	`string`	`null`	監控紀錄的唯一識別碼。選填。

請求範例

GET /monitors-groups/group-id-1/run

回應範例

{
  "result": "OK",
  "monitorLogId": "monitor-log-id-1"
}

Cron 監控

Cron 監控透過 HTTP ping 追蹤排程工作。關於產品設定與儀表板用法，請參閱 Cron 監控。

欄位的可用值

Cron 監控狀態

值	說明
`UP`	監控運行正常
`DOWN`	監控失敗
`DEGRADED`	監控出現問題
`UNKNOWN`	無法判斷監控狀態

Cron 監控運作狀態

值	說明
`ACTIVE`	監控正在持續檢查中
`PAUSED`	監控檢查已暫停
`MUTED`	監控已靜音（不發送通知）

Cron 監控紀錄狀態

值	說明
`SUCCESS`	工作順利完成
`FAILURE`	工作明確回報失敗
`MISSED`	工作沒有在預期時間內 ping
`LATE`	工作在週期之後、但仍在寬限時間內 ping
`STARTED`	工作回報已開始執行（用於計算執行時間）

週期與寬限時間

period 與 grace 都以秒為單位。period 是工作應該多久執行一次；grace 是在監控被標記為故障之前額外允許的時間。

取得 Cron 監控

端點：

GET /:page_id/monitors/cron

查詢參數

參數	型別	預設值	說明
`limit`	`number`	`100`	每頁的 cron 監控數量，最多 100。
`page`	`number`	`1`	頁碼。
`search`	`string`	`null`	依名稱篩選結果的搜尋字詞。
`status`	`enum`	`null`	狀態篩選（'UP'、'DOWN'、'UNKNOWN'、'DEGRADED'）。

請求範例

GET /page123/monitors/cron?limit=10&page=1&status=DOWN

回應範例

{
  "cronMonitors": [
    {
      "id": "cron-abc123",
      "name": "Daily backup",
      "slug": "my-page-x7k2m9n4p1q8w3e5",
      "period": 86400,
      "grace": 3600,
      "status": "UP",
      "state": "ACTIVE",
      "siteId": "page123",
      "order": 1,
      "groupId": null,
      "componentId": "component-id-1",
      "onFailCreateIncident": true,
      "onFailCreateOutageDuration": false,
      "onFailPublishIncident": true,
      "onFailNotifySubscribers": true,
      "onRecoverResolveIncident": true,
      "onRecoverResolveOutageDuration": false,
      "onRecoverPublishIncident": true,
      "onRecoverNotifySubscribers": true,
      "createTemplateId": null,
      "resolveTemplateId": null,
      "createdAt": "2024-01-15T08:00:00.000Z",
      "updatedAt": "2024-01-15T08:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1,
  "limit": 10
}

建立 Cron 監控

端點：

POST /monitors/cron

請求範例

{
  "pageId": "page123",
  "name": "Daily backup",
  "period": 86400,
  "grace": 3600,
  "alerts": ["alert-id-1", "alert-id-2"],
  "createComponent": true,
  "onFail": {
    "createIncident": true,
    "createOutageDuration": false,
    "publishIncident": true,
    "notifySubscribers": true
  },
  "onRecover": {
    "resolveIncident": true,
    "resolveOutageDuration": false,
    "publishIncident": true,
    "notifySubscribers": true
  }
}

回應範例

{
  "cronMonitor": {
    "id": "cron-abc123",
    "name": "Daily backup",
    "slug": "my-page-x7k2m9n4p1q8w3e5",
    "period": 86400,
    "grace": 3600,
    "status": "UP",
    "state": "ACTIVE",
    "siteId": "page123",
    "order": 1,
    "groupId": null,
    "componentId": "component-id-1",
    "onFailCreateIncident": true,
    "onFailCreateOutageDuration": false,
    "onFailPublishIncident": true,
    "onFailNotifySubscribers": true,
    "onRecoverResolveIncident": true,
    "onRecoverResolveOutageDuration": false,
    "onRecoverPublishIncident": true,
    "onRecoverNotifySubscribers": true,
    "createTemplateId": null,
    "resolveTemplateId": null,
    "createdAt": "2024-01-15T08:00:00.000Z",
    "updatedAt": "2024-01-15T08:00:00.000Z"
  },
  "message": "Cron monitor created successfully."
}

回應中包含一個 slug。用它來組出工作的 ping URL。第一次成功的 ping 會排定背景檢查工作。

更新 Cron 監控

端點：

PUT /monitors/cron/:id

請求範例

{
  "name": "Daily backup (updated)",
  "period": 43200,
  "grace": 1800,
  "state": "PAUSED",
  "alerts": ["alert-id-1"],
  "onFail": {
    "notifySubscribers": false
  }
}

回應範例

{
  "cronMonitor": {
    "id": "cron-abc123",
    "name": "Daily backup (updated)",
    "slug": "my-page-x7k2m9n4p1q8w3e5",
    "period": 43200,
    "grace": 1800,
    "status": "UP",
    "state": "PAUSED",
    "siteId": "page123",
    "order": 1,
    "groupId": null,
    "componentId": "component-id-1",
    "onFailCreateIncident": true,
    "onFailCreateOutageDuration": false,
    "onFailPublishIncident": true,
    "onFailNotifySubscribers": false,
    "onRecoverResolveIncident": true,
    "onRecoverResolveOutageDuration": false,
    "onRecoverPublishIncident": true,
    "onRecoverNotifySubscribers": true,
    "createTemplateId": null,
    "resolveTemplateId": null,
    "alerts": [
      {
        "id": "alert-id-1",
        "type": "EMAIL",
        "recipient": "ops@example.com"
      }
    ],
    "createdAt": "2024-01-15T08:00:00.000Z",
    "updatedAt": "2024-01-16T10:30:00.000Z"
  },
  "message": "Cron monitor updated successfully."
}

刪除 Cron 監控

端點：

DELETE /monitors/cron/:id

請求範例

DELETE /monitors/cron/cron-abc123

回應範例

{
  "cronMonitor": {
    "id": "cron-abc123",
    "name": "Daily backup",
    "slug": "my-page-x7k2m9n4p1q8w3e5",
    "period": 86400,
    "grace": 3600,
    "status": "UP",
    "state": "ACTIVE",
    "siteId": "page123",
    "order": 1,
    "groupId": null,
    "componentId": "component-id-1",
    "onFailCreateIncident": true,
    "onFailCreateOutageDuration": false,
    "onFailPublishIncident": true,
    "onFailNotifySubscribers": true,
    "onRecoverResolveIncident": true,
    "onRecoverResolveOutageDuration": false,
    "onRecoverPublishIncident": true,
    "onRecoverNotifySubscribers": true,
    "createTemplateId": null,
    "resolveTemplateId": null,
    "createdAt": "2024-01-15T08:00:00.000Z",
    "updatedAt": "2024-01-15T08:00:00.000Z"
  },
  "message": "Cron monitor deleted successfully."
}

取得 Cron 監控紀錄

端點：

GET /monitors/cron/:id/logs

查詢參數

參數	型別	預設值	說明
`limit`	`number`	`100`	每頁的紀錄數，最多 127。
`page`	`number`	`1`	頁碼，最大值為 1000。
`startDate`	`string`	一年前	紀錄範圍的 ISO 8601 起始日期。
`endDate`	`string`	現在	紀錄範圍的 ISO 8601 結束日期。
`importance`	`enum`	`null`	依重要性篩選紀錄（'all'、'important'）。

請求範例

GET /monitors/cron/cron-abc123/logs?limit=50&page=1&importance=important

回應範例

{
  "logs": [
    {
      "id": "log-xyz789",
      "monitorId": "cron-abc123",
      "status": "SUCCESS",
      "requestType": "GET",
      "agent": "curl/8.4.0",
      "ipAddress": "203.0.113.10",
      "createdAt": "2024-01-16T06:00:00.000Z",
      "startedAt": "2024-01-16T05:59:58.000Z"
    }
  ],
  "page": 1
}

取得 Cron 監控摘要

端點：

GET /monitors/cron/:id/summary

請求範例

GET /monitors/cron/cron-abc123/summary

回應範例

{
  "summary": {
    "totalLogs": 120,
    "totalFailedLogs": 3,
    "availability": 97.5,
    "oneDayAvailability": 100,
    "previousDayAvailability": 100,
    "sevenDayAvailability": 98.2,
    "previousSevenDayAvailability": 96.1,
    "thirtyDayAvailability": 97.5,
    "previousThirtyDayAvailability": 95.8,
    "lastSuccess": "2024-01-16T06:00:00.000Z",
    "lastFailure": "2024-01-10T06:00:00.000Z",
    "lastStarted": null,
    "upSince": "2024-01-10T07:00:00.000Z",
    "downSince": null
  }
}

Ping 端點

這些端點不需要驗證。監控的 slug 本身就是密鑰。

你可以透過 API 基礎 URL 或專用的 cron 主機來 ping：

成功： https://cron.instatus.com/{slug} 或 GET / POST / HEAD /monitors/cron/{slug}
失敗： https://cron.instatus.com/{slug}/fail 或 GET / POST / HEAD /monitors/cron/{slug}/fail
開始： https://cron.instatus.com/{slug}/start 或 GET / POST / HEAD /monitors/cron/{slug}/start

每次工作按時完成時就送出一次成功 ping。若要記錄執行時間，可在工作開始前送出 start ping，結束時再送出成功或失敗的 ping。

成功 ping 範例

curl https://cron.instatus.com/my-page-x7k2m9n4p1q8w3e5

回應範例

{
  "id": "log-xyz789",
  "monitorId": "cron-abc123",
  "status": "SUCCESS",
  "requestType": "GET",
  "agent": "curl/8.4.0",
  "ipAddress": "203.0.113.10",
  "createdAt": "2024-01-16T06:00:00.000Z"
}

如果 slug 無效，回應會是：

{
  "message": "Monitor not found"
}