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
- Other Functions
- Locating a Primary Key (PK) Value
- Sample Use Case
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.
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, 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:
Users can list all Status Pages from the StatusPages endpoints. Additionally, users can create, edit, or delete status pages and incidents.
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.
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.
Need more information on the Uptime.com REST API? Contact firstname.lastname@example.org.