Account and Security

API scopes, limits, pagination, and safe automation

Understand Uptime Basics API permissions, plan allowances, pagination cursors, idempotency, and safe retry behavior.

Article ACC-014 By Uptime Basics Support Reviewed August 1, 2026

The Uptime Basics API is a separate, versioned interface at https://api.uptimebasics.com/v1. It does not expose the customer dashboard, billing, profile, administrator, monitor credentials, saved authentication headers, or payment data.

API permissions

Select only the scopes an application needs:

monitors:read reads safe monitor configuration and current status.
monitors:create creates monitors and queues their first check.
monitors:update changes supported monitor settings.
monitors:control pauses or activates monitors.
monitors:archive archives or reactivates monitors without deleting retained history.
incidents:read reads incidents for an owned monitor.
alerts:read reads safe alert-delivery history.
alerts:write selects verified destinations and changes per-monitor alert settings.
checks:read reads retained check-level results on Pro.
exports:create requests a bounded asynchronous check-log export.
exports:read reads export progress and creates short-lived download links.
status-pages:read reads status-page configuration.
status-pages:write enables, disables, and changes safe status-page content.

Older tokens can contain monitors:write; those tokens remain compatible with their existing safe monitor controls. New tokens use the narrower scopes above. A token cannot gain permissions that are unavailable to the current plan. Changing plans can therefore reduce the effective scopes of an existing token.

The API does not return Basic Authentication passwords, custom request-header values, webhook signing secrets, billing data, or other customer secrets.

Request allowances

Account state	Requests per month	Requests per minute
Trial	1,000	10
Starter	5,000	10
Plus	25,000	30
Pro	100,000	60

The monthly period uses UTC and changes on the first day of the month. Account > Integrations shows current usage. Authorized requests count toward the allowance, including requests that return a validation or not-found response.

The account page and API identify usage as warning at 80%, critical at 90%, and exhausted at 100%. These warnings help you adjust an integration before requests are rejected.

When a limit is reached, the API returns HTTP 429 with a Retry-After header. Do not immediately retry in a tight loop. The authenticated GET /usage route returns the current count, remaining allowance, warning level, and UTC reset time.

Response and rate-limit headers

Every API response includes X-Request-Id. Keep this value when troubleshooting a failed request or contacting support.

Authorized responses also include:

X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the active per-minute allowance;
X-RateLimit-Monthly-Limit, X-RateLimit-Monthly-Remaining, and X-RateLimit-Monthly-Reset when monthly usage is available; and
X-RateLimit-Warning after monthly usage reaches a warning threshold.

Reset headers contain Unix timestamps. Error responses use a consistent error.code, error.message, and error.requestId structure.

Discover available capabilities

Use authenticated GET /capabilities when an integration needs to adapt to different plans or token scopes. It returns the token's effective scopes, plan limits, available webhook events, and the API features currently enabled for that account.

Do not hard-code access based only on a plan name. A token can have fewer scopes than the plan permits, and some API operations can be introduced behind controlled feature flags.

Pagination

List routes accept limit values from 1 to 100 and can return pagination.nextCursor. Treat the cursor as an opaque value:

send the first request without a cursor;
process the returned data;
if nextCursor is not null, send it unchanged in the next request; and
stop when nextCursor is null.

Do not construct or modify cursors. A cursor applies to the same route and account that produced it.

Read monitor and reliability data

The read API exposes the customer-safe state used for common dashboard and reporting workflows:

GET /monitors lists monitors. It supports status, enabled, type, updated_after, and updated_before filters.
GET /monitors/{monitorId} includes the current HTTP state, slow-response configuration, and SSL/domain-expiry summary.
GET /monitors/{monitorId}/summary returns bounded uptime and response-time rollups.
GET /monitors/{monitorId}/checks returns retained check records on Pro.
GET /incidents and GET /monitors/{monitorId}/incidents return cursor-paginated incident history.
GET /alerts and GET /monitors/{monitorId}/alerts return safe alert-delivery history.
GET /status-pages lists configured customer status pages.

Incident and alert list records contain opaque id values. Use those values unchanged with GET /incidents/{incidentId} or GET /alerts/{alertId}. Do not decode them or build identifiers from timestamps.

Incident detail includes a bounded activity sample and a customer-safe diagnostics summary. It does not return saved request headers, credentials, raw response bodies, or internal infrastructure identifiers. For a complete route and field reference, use the OpenAPI contract.

Monitor-restricted tokens apply their selected-monitor list to tenant-wide incident, alert, and status-page routes. An inaccessible detail returns 404, so a token cannot use the API to confirm that an unapproved resource exists.

Safe write requests

Every monitor write requires an Idempotency-Key header between 8 and 128 characters. Generate a unique value for one intended action and reuse that same value only when retrying the identical request.

If the first response is lost, an identical retry can return the saved result. Reusing the key for different input returns a conflict instead of performing an ambiguous action.

POST /monitors validates the target, current plan limits, duplicate monitors, verified alert destinations, and protected request settings before saving anything. A newly created or reactivated monitor remains pending until its queued first check returns evidence.

Monitor detail and write responses include an ETag. Send that value in If-Match when updating, archiving, or reactivating a monitor. If another request changed the monitor first, the API returns 412 Precondition Failed; fetch the current monitor and decide whether to retry. Missing If-Match returns 428 Precondition Required.

API monitor controls use the same account-state, plan, destination, secret-encryption, and lifecycle rules as the dashboard. Archive preserves the monitor and its retained history. Reactivation revalidates capacity and target safety before checking resumes.

Permanent monitor deletion remains dashboard-only. This avoids irreversible deletion by a leaked automation token.

Alert destinations and slow-response settings

The API can select an existing verified email address or phone number, but it cannot add or verify a destination:

Add and verify the destination under Account > Alerts.
Use GET /alert-destinations with alerts:write to retrieve its stable destination ID.
Send that ID to PATCH /monitors/{monitorId}/alert-settings with the current monitor ETag and a unique Idempotency-Key.

The same alert-settings route controls email and SMS channel toggles, the slow-response threshold, and the consecutive-check confirmation count. Enabling a channel without a matching verified destination is rejected. Removing verification in the account prevents that destination from being selected by later API writes.

Verification codes, pending verification state, and destination-creation routes are not part of the customer API. This prevents a leaked automation token from enrolling a new recipient.

Safe status-page controls

Create the initial public status page and reserve its slug in the dashboard. An API token with status-pages:write can then use PATCH /monitors/{monitorId}/status-page to:

enable or disable the shared status page;
change its title and description;
control search indexing with noindex; and
show or hide the uptime timeline, response-time chart, incidents, and recent history.

The write requires the current ETag and an Idempotency-Key. Uptime Basics updates the public snapshot after saving the configuration.

The API cannot change the slug, ownership-verification evidence, branding assets, styles, analytics identifier, or custom domain. Certificate requests, DNS activation, managed edge-network changes, and enabling or disabling a page with a managed custom domain remain dashboard-only. These restrictions preserve website-ownership and abuse-prevention gates.

Asynchronous check-log exports

Paid accounts can request a check-log CSV without holding an API connection open:

Send POST /exports with exports:create, an Idempotency-Key, the accessible monitorId, and an optional retained date range and filters.
Poll GET /exports/{exportId} with exports:read until its status is ready or failed.
When it is ready, call GET /exports/{exportId}/download to receive a private download URL that lasts no more than five minutes.

The job runs on a separate bounded worker. Each account can have at most two queued or processing exports. A request can cover no more than the current 30-day raw-check retention window and can contain no more than 50,000 matching checks.

Ready files remain available for six hours and are then treated as expired. The private artifact bucket also deletes temporary objects automatically. Creating a new download link does not extend the artifact lifetime.

CSV cells are quoted and values that could be interpreted as spreadsheet formulas receive a protective prefix. Exports contain check evidence only; they do not contain saved Basic Authentication passwords, authorization values, custom request-header secrets, customer API tokens, or internal artifact identifiers.

Uptime Basics sends the verified account email a completion or failure notice when possible. The email does not contain a permanent download link. Use the authenticated export routes to retrieve the current result.

Retry guidance

Retry 429, 500, 502, 503, and 504 responses with exponential backoff and random jitter.
Respect Retry-After when present.
Do not retry 400, 401, 403, or 404 until the request, token, scope, or resource has been corrected.
Set a client timeout and cap retries so one failing integration cannot create an endless request loop.

The OpenAPI contract is available at /developers/openapi.yaml.

Did this answer your question?

Your response helps improve this Help Center.