Getting Started with the REST API

The REST API offers the functionality of the Uptime UI, with the advantage of automated reporting based on triggers from your system. 

We maintain API documentation, and a browsable API version.    

Table of Contents

How to Use the REST API

To locate your API token, click Settings>API. You will see the following screen, which contains some instructions on using your API Key:

Programmatic access requires passing the API key we provide via HTTP Header. 

You may use this Auth endpoint to login with the email and password you use for to retrieve your access token:

The REST API uses GET, POST, PUT, PATCH, and DELETE endpoints. The following section breaks down what these endpoints do. 

Please note: To ensure high performance and fair access of the API for all our customers, enforces fair use limits on API calls. Review the API access in your account for more details.


Alert endpoints allow users to list all alerts, or get the details of a single alert. Alerts are listed by date and updated in one-minute intervals. Users can also get Root Cause Analysis data for a specified location, or toggle the “ignore” state for a specific alert. 

Typical alert data includes:

  • Alert state
  • Ignore state
  • Number of locations reporting down
  • Check service number (Check_pk)
  • Details about the check as configured (URL, check name, date created, etc.)
  • Check type


Users can list all outages or get the details of a single outage with the Outage endpoints. Outages are updated in one-minute intervals, and is the best place to see whether a check has come UP since an alert was issued.


Users can generate access tokens, or login with an email and password to retrieve an access token from Auth endpoints. Additionally, users can investigate the details of an authenticated user, reset password, and download a CSV containing usage info for your current plan. 


Create a specific check type, remove, or edit existing checks from the Checks endpoints. You may also list all existing checks, as well as set escalation and maintenance windows, assign contacts, and set probe server locations to use for a specific check or in bulk for up to 250 checks simultaneously. Additionally, you can investigate all available check parameters.

  • Check_state_is_up can be either true or false, and is updated in one-minute intervals.
  • Cached_uptime is a 30-day average that is updated daily.
  • Cached_Response_time shows a 30-minute response time average across all locations, and it is updated every 15 minutes. 

Utilize the Check-Tags endpoints to set or edit tags. You may also create, delete or partially update a tag. 

NOTE: full one-minute response time metrics are available via the API endpoint:

Status Pages

Users can list all Status Pages from the StatusPages endpoints. Additionally, users can create, edit, or delete status pages and incidents. 

Other Functions

Contacts and Users

Create, edit, and delete contacts with the Contacts endpoints. This endpoint also allows on-call scheduling.  

Create, edit, and delete users with the Users endpoints. These endpoints also allow account owners to reactivate and deactivate users.


Create, edit, or delete a specific integration from one of our integration partners with the Integrations endpoints. Users can also list existing integrations.

Probe Servers

List all probe servers that uses from the Probe Servers endpoint


Get Dashboard data, including statistics in real-time, from the Dashboards endpoints

Locating a Primary Key (PK) Value

A Primary Key, or “PK” value, is required depending on the endpoint you are using. To query for a specific check, user, alert, or status page, you will need to know its pk value. We suggest using the “list all” endpoint that corresponds with the value you need. You can locate the PK values and use those values as needed.

For example, use the Checks>List All endpoint or Alerts>List All endpoint.

Here is a sample of JSON output from the endpoint Checks>List All. We have bolded the PK value:

 "pk": 123456,
      "url": "",
      "name": "API Use Case",
      "cached_response_time": 0.158125866666667,
      "contact_groups": [
      "created_at": "2019-11-12T20:36:01.186247Z",
      "modified_at": "2020-06-01T16:44:33.148122Z",
      "locations": [
        "US East",
        "US West",
        "US Central"
      "tags": [
        "Tech news",
        "Test cases"

Sample Use Case | Find Which Checks are Down at a Given Time

This use case will show you how to query various endpoints from, and determine which checks are down at the time the query is run. 

  1. Query the /checks/ endpoint for all checks in 15-minute intervals. This query will provide you a fresh checks listing that includes up or down status and response time statistics.
  2. Query the /outages/ endpoint once per minute. This query will provide you a list of the latest outages for display without separating down and up alerts.
  3. Query the /alerts/ endpoint once per minute to get any new UP/DOWN alerts. The results from this endpoint can be used to update the checks listing in memory with any new UP/DOWN changes and eliminate the need to read all the checks again.

Require Assistance?

Need more information on the REST API? Contact

Was this article helpful?
0 out of 0 found this helpful