The Uptime.com REST API offers the functionality of the Uptime UI, with the advantage of automated reporting based on triggers from your system.
Table of Contents
- How to Use the REST API
- Status Pages
- SLA Reports
- Scheduled Reporting
- Other Functions
- Locating a Primary Key (PK) Value
- Sample Use Case: Find Which Checks are Down at a Given Time
- Sample Use Case: Query SLA Reporting Efficiently
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 Uptime.com 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.
Resetting Your API Token
Locate your API key from the API Token page, then click on Generate new key and follow the prompts. The current API key is removed when you generate a new key, so API calls using the previous key will fail until the new key is replaced.
Please note: To ensure high performance and fair access of the API for all our customers, Uptime.com 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, create new or list existing subaccounts, 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 check. 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.
Bulk endpoints offer requests to help users with larger accounts stay within fair use limits. These bulk endpoints have some limitations to be aware of:
- Bulk endpoints can query up to 250 checks simultaneously
- Response time data is limited to a 30 day period
- Response time data is always the daily average
We suggest using an individual check endpoint for greater precision.
NOTE: full one-minute response time metrics are available via the API endpoint:
Create, list, update, get, and delete SLA reports from the SLA-Reports endpoints. Additionally, users can specify a default time period for each report.
Users can create, list, update, get, and delete scheduled reports with the Scheduled-Reports endpoints.
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, retrieve a list of users assigned to a specific subaccount, or set two-factor authentication requirements.
Create, edit, or delete a specific integration from one of our integration partners with the Integrations endpoints. Users can also list existing integrations.
List all probe servers that Uptime.com uses from the Probe Servers endpoint.
Get Dashboard data, including statistics in real-time, from the Dashboards endpoints.
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.
Here is a sample of JSON output from the endpoint Checks>List All. We have bolded the PK value:
"pk": 123456, "url": "https://uptime.com/api/v1/checks/123456/", "name": "API Use Case", "cached_response_time": 0.158125866666667, "contact_groups": [ "geckoboard_testing" ], "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" ]
This use case will show you how to query various endpoints from Uptime.com, and determine which checks are down at the time the query is run.
- 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.
- 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.
- 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.
This use case is designed to retrieve data from an SLA report you create.
Let us assume you have 100 checks and you need to know performance statistics and uptime % for a specific period (for example, 30 days). An SLA report is well suited to this use case because it utilizes checks grouped together by tag(s).
We will first create a tag, assign it to checks, and then use this tag to build our SLA report.
The endpoint /check-tags/check_tags_create creates the tag in question. We will use “SLA_Reporting” and set the color_hex value to blue:
We can apply this tag to the 100 checks needed at the /checks/checks_bulk_update_partial_update endpoint. Here is an example that assigns the tag “SLA_Reporting” to six checks (See PK value):
"pk": [1, 2, 3, 4, 5, 6],
Next, create an SLA report. Ensure that you include the desired tag to assign checks to the report:
"name": "SLA Report by Tag",
Note, the example here omits the "services_selected" parameter because we only want our report to populate with checks that use this tag.
The above includes all services by tag, and delivers data on the previous 30 days. As new checks are added or assigned to this tag, they will populate in our SLA report. There is a limit of 250 services per report.
Need more information on the Uptime.com REST API? Contact firstname.lastname@example.org.