Getting Started with the Uptime.com REST API

The Uptime.com 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:

https://lh3.googleusercontent.com/J0Jr0eJPOk8YOELI-r9LMaRHAswL6qbH6phpkAFsUvBu3y1r-Ys7IcpReI-lEwNW2r6PNJlo6FYZ8U7krwNks0MoY0H0zaPhn0mxAwgbzlaUxIi_wu0D3MJA3TnoXpyGLWJarhwy

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.

Alerts 

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

Outages

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.

Auth

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. 

Checks

Create a specific check type, remove or edit existing checks from the Checks endpoints. You may also list all existing checks, set escalation and maintenance windows, assign contacts, and set probe server locations to use for a specific 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. 

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.

Integrations

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 Uptime.com uses from the Probe Servers endpoint

Dashboard

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

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

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. 

  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 Uptime.com REST API? Contact support@uptime.com

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