List maintenance occurrences Beta
GET /api/v1/maintenance/occurrences
Occurrences that overlap a time range, across all windows or for one, oldest first. Cancelled occurrences aren't listed.
Needs an X-API-Key header whose owner has access to uptime monitoring in the app. The call counts once against your daily quota. See Monitoring API: getting started for authentication, rate limits and errors.
Query parameters
| Name | Type | Description |
|---|---|---|
maintenanceId optional | string | Only this window's occurrences. |
from optional | string | integer | ISO 8601 or UNIX seconds. Default: now. |
to optional | string | integer | ISO 8601 or UNIX seconds. Default: 90 days from now. Must be after from. |
page optional | integer | Page number, starting at 1. Default 1. |
per optional | integer | Occurrences per page, 1 to 1000. Default 100. |
Request
Response
200 · application/json
- {
- "total": 13, "page": 1, "per": 2,
- "occurrences": [
- { "id": "48213", "maintenanceId": "mw_3f9a0c1d2e4b5a6c7d8e", "description": "Weekly database backup",
- "from": "2026-09-20T02:00:00.000Z", "to": "2026-09-20T03:00:00.000Z", "modified": false },
- { "id": "48214", "maintenanceId": "mw_3f9a0c1d2e4b5a6c7d8e", "description": "Weekly database backup",
- "from": "2026-09-27T03:00:00.000Z", "to": "2026-09-27T04:00:00.000Z", "modified": true }
- ],
- "usage": { "used": 36, "dailyLimit": 100, "tier": "free" }
- }
modified is true for an occurrence that was moved on its own.
Errors
| Status | When |
|---|---|
400 | from or to isn't a valid time, or from isn't before to. |
401 | The API key is missing or invalid. |
403 | The key's owner doesn't have access to uptime monitoring, or the key isn't linked to a workspace. |
405 | The endpoint doesn't accept that method. |
429 | A rate limit or your daily quota was hit. Read Retry-After, in seconds. |
500 | Something went wrong on our side. Try again. |
503 | The API is temporarily unavailable. Try again shortly. |
Errors are JSON: { "error": "message" }. See Monitoring API errors.
Related
- Maintenance windows: how maintenance works and the window object
- Move an occurrence: change one of them
- Cancel several occurrences: in one call