#Rate limits

The API is free to read, so it is rate limited to keep it fast for everyone. Limits apply per API token, in one-minute windows.

#Headers

Successful responses report the current window:

When you go over, the response is 429 Too Many Requests with "error": "rate_limited" and a Retry-After header in seconds. Wait that long, then continue.

import time, requests

def get(url, key):
    while True:
        response = requests.get(url, headers={"X-API-Key": key})
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "5")))

#Polling status

Monitors are checked on their own schedule (every 10 seconds at the fastest), so polling more often than a monitor's interval returns the same answer. To watch many monitors, call GET /api/v1/monitors once per interval instead of fetching each monitor; it returns every monitor's current_status. To be told about outages instead of polling, add a notification contact.

#Fair use

UpHeron monitors services you operate or are allowed to monitor. Using monitors to load-test, flood or probe third-party services is not allowed. Tokens or workspaces used for abuse are revoked without refund.