Status Page Subscribers

Overview

Visitors can subscribe to a status page by email to receive incident and maintenance notifications. These endpoints let you manage that list.

Action	Endpoint
List	`GET /api/projects/{projectId}/status-pages/{statusPageId}/subscribers`
Update preferences	`PATCH /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/{subscriberId}`
Delete	`DELETE /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/{subscriberId}`
Bulk delete	`POST /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/bulk-delete`
Bulk notify	`POST /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/bulk-notify`
Export CSV	`GET /api/projects/{projectId}/status-pages/{statusPageId}/subscribers/export`

Authentication

Header	Required	Description
`X-API-Key`	Yes	Your API key (`Authorization: Bearer {jwt}` also works). Write requests need the `read_write` scope.
`Content-Type`	Yes (when sending a body)	`application/json`

Required access: project viewer or higher to list; project admin for everything else, including export. No X-Project-ID header is needed.

Path parameters

Parameter	Type	Description
`projectId`	UUID	The project
`statusPageId`	UUID	The status page
`subscriberId`	UUID	The subscriber

List subscribers

Query parameters

Parameter	Type	Default	Description
`status`	string	`all`	`verified`, `unverified`, `unsubscribed` or `all`
`preference`	string	-	Only subscribers with this preference on: `critical_incidents`, `all_incidents` or `maintenance`
`search`	string	-	Search by email
`sort`	string	`subscribed_at`	`email`, `subscribed_at` or `verified_at`
`order`	string	`desc`	`asc` or `desc`
`page`	integer	`1`	Page number, 1 or greater
`limit`	integer	`50`	Page size, 10-1000

Response (200)

{
  "success": true,
  "data": {
    "subscribers": [
      {
        "id": "d4c3b2a1-f0e9-4d8c-b7a6-5f4e3d2c1b0a",
        "status_page_id": "0b7c3a52-7d57-4c35-9f0e-5a3b6f1f2a10",
        "email": "[email protected]",
        "webhook_url": null,
        "is_verified": true,
        "verification_expires_at": null,
        "preferences": {
          "critical_incidents": true,
          "all_incidents": false,
          "maintenance": true,
          "frequency": "immediate"
        },
        "unsubscribed_at": null,
        "subscribed_at": "2026-09-01T09:00:00.000Z",
        "verified_at": "2026-09-01T09:02:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total_count": 1,
      "has_more": false
    }
  }
}

Subscriber objects never include verification or unsubscribe tokens. Those are only sent to the subscriber in their own email links. Subscriber email addresses are still personal data, so treat list responses as sensitive.

cURL

curl "https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers?status=verified&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

Update subscriber preferences

Field	Type	Required	Description
`preferences`	object	Yes	At least this wrapper object
`preferences.critical_incidents`	boolean	No	Notify about critical incidents
`preferences.all_incidents`	boolean	No	Notify about all incidents
`preferences.maintenance`	boolean	No	Notify about maintenance
`preferences.frequency`	string	No	`immediate`, `hourly` or `daily`

Response (200): { "success": true, "data": { "subscriber": { ... }, "message": "Subscriber preferences updated successfully" } }

cURL

curl -X PATCH https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/YOUR_SUBSCRIBER_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preferences": { "all_incidents": true, "frequency": "daily" } }'

Delete a subscriber

Response (200): { "success": true, "data": { "message": "Subscriber deleted successfully" } }

cURL

curl -X DELETE https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/YOUR_SUBSCRIBER_ID \
  -H "X-API-Key: YOUR_API_KEY"

Bulk delete

Field	Type	Required	Description
`subscriber_ids`	UUID[]	Yes	At least one subscriber

Response (200):

{
  "success": true,
  "data": {
    "result": {
      "success_count": 2,
      "failed_count": 0,
      "errors": []
    },
    "message": "Successfully deleted 2 of 2 subscribers"
  }
}

errors contains { "subscriber_id", "error" } entries for any that failed.

cURL

curl -X POST https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/bulk-delete \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subscriber_ids": ["YOUR_SUBSCRIBER_ID_1", "YOUR_SUBSCRIBER_ID_2"] }'

Bulk notify

Sends a custom email to the selected subscribers. Only verified subscribers who have not unsubscribed receive it; others are skipped.

Field	Type	Required	Description
`subscriber_ids`	UUID[]	Yes	At least one subscriber
`subject`	string	Yes	1-200 characters
`message`	string	Yes	1-5000 characters

Response (200): same shape as bulk delete, with message reading Successfully notified {n} of {total} subscribers.

cURL

curl -X POST https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/bulk-notify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_ids": ["YOUR_SUBSCRIBER_ID"],
    "subject": "Planned maintenance on Saturday",
    "message": "We will be performing maintenance from 02:00 to 03:00 UTC."
  }'

Export CSV

Returns up to 10,000 subscribers as a CSV file (Content-Type: text/csv). It accepts the status, preference and search filters from the list endpoint. Columns: Email, Status, Subscribed At, Verified At, Critical Incidents, All Incidents, Maintenance, Frequency, Webhook URL.

cURL

curl "https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/subscribers/export?status=verified" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o subscribers.csv

Errors

Status	Code	Cause
400	`VALIDATION_ERROR`	Invalid body or query parameter
401	`AUTHENTICATION_REQUIRED`	Missing or invalid credentials
403	`INSUFFICIENT_PERMISSIONS`	Write or export without project admin access
403	`ACCESS_DENIED`	No access to the project, or the page belongs to another project
403	`API_KEY_ORGANIZATION_MISMATCH`	The API key belongs to a different organization than the project
403	`READ_ONLY_API_KEY`	The API key has the `read` scope and the request writes data
404	`RESOURCE_NOT_FOUND`	The status page or subscriber does not exist

Introduction

Monitors

Groups

Incidents

Status Pages

Status Page Incidents

Status Page Subscribers

Overview

Authentication

Path parameters

List subscribers

Query parameters

Response (200)

Update subscriber preferences

Delete a subscriber

Bulk delete

Bulk notify

Export CSV

Errors

​Overview

​Authentication

​Path parameters

​List subscribers

​Query parameters

​Response (200)

​Update subscriber preferences

​Delete a subscriber

​Bulk delete

​Bulk notify

​Export CSV

​Errors

Overview

Authentication

Path parameters

List subscribers

Query parameters

Response (200)

Update subscriber preferences

Delete a subscriber

Bulk delete

Bulk notify

Export CSV

Errors