All API calls requires authentication with an API key which can be passed either as an URL query parameter
?api-key=
or as an HTTP header X-API-KEY:
Sign in to see your API key.
We also offer read-only API key so you can build public integrations (like a truly custom status page or TV dashboard) directly in javascript without giving away your read/write access. If you make this API key publicly accessible, for example through javascript, be careful! All your checks will be visible including the URL parameters and custom HTTP headers which might leak sensitive information. This API key will only work with GET endpoints (green).
All API calls supports gzip compression and we recommend enabling it to increase response speed and save bandwidth. This can be achieve by passing the standard
Accept-Encoding: gzip
HTTP header or by using the native option provided by your HTTP client. For example with curl you can add the --compressed
option (which automatically adds the header and decompress the response). This usually gives 4-6 times smaller payloads and even on a very good fiber connection, a 20-50% faster response time.
Here are some existing client libraries/tools to work with the API:
URLs returned here will not include basic auth credentials if any, for security reasons. So be careful when re-using this URL for update at the risk of erasing the credentials.
curl https://updown.io/api/checks?api-key=:apikey
[ { "token": "ngg8", "url": "https://updown.io", "alias": "", "last_status": 200, "uptime": 100, "down": false, "down_since": null, "up_since": "2023-12-23T09:06:51Z", "error": null, "period": 15, "apdex_t": 0.5, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": ["email:1246848337", "sms:231178295"], "last_check_at": "2021-12-17T05:00:01Z", "next_check_at": "2021-12-17T05:00:16Z", "created_at": "2012-09-22T13:29:44Z", "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "", "ssl": { "tested_at": "2021-12-17T04:58:04Z", "expires_at": "2022-02-21T15:57:36Z", "valid": true, "error": null } } ]
URLs returned here will not include basic auth credentials if any, for security reasons. So be careful when re-using this URL for update at the risk of erasing the credentials.
curl https://updown.io/api/checks/:token?api-key=:apikey
{ "token": "ngg8", "url": "https://updown.io", "alias": "", "last_status": 200, "uptime": 100, "down": false, "down_since": null, "up_since": "2023-12-23T09:06:51Z", "error": null, "period": 15, "apdex_t": 0.5, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": ["email:1246848337", "sms:231178295"], "last_check_at": "2021-12-17T05:00:01Z", "next_check_at": "2021-12-17T05:00:16Z", "created_at": "2012-09-22T13:29:44Z", "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "", "ssl": { "tested_at": "2021-12-17T04:58:04Z", "expires_at": "2022-02-21T15:57:36Z", "valid": true, "error": null } }
Accept-Encoding: gzip
)
curl https://updown.io/api/checks/:token/downtimes?api-key=:apikey
[ { "id": "66f255685d3c15c3bbe8fd6e", "details_url": "https://updown.io/downtimes/66f255685d3c15c3bbe8fd6e", "error": "Connection timeout (10 seconds)", "started_at": "2024-09-24T05:59:32Z", "ended_at": "2024-09-24T08:06:08Z", "duration": 7596, "partial": false }, { "id": "66f2541c4fe3629362cb5120", "details_url": "https://updown.io/downtimes/66f2541c4fe3629362cb5120", "error": "TLS handshake timeout (10 seconds)", "started_at": "2024-09-24T05:53:14Z", "ended_at": "2024-09-24T05:56:37Z", "duration": 203, "partial": false } ]
Statistic are aggregated per hour which means you can't get more precise results than this. For example all requests performed between 5:00 and 5:59 will be reported at 5:00 in this API. The time range needs to be at least one hour to get some data.
Furthermore, after 2 days metrics are aggregated by day instead (single entry at 12pm), and after 40 days they are aggregated by month (single entry on the 16th). When groupping by 'time', you'll see this in the group
attribute.
The uptime
attribute is not supported when using group.
curl https://updown.io/api/checks/:token/metrics?api-key=:apikey
{ "uptime": 99.999, "apdex": 0.999, "requests": { "samples": 87441, "failures": 2, "satisfied": 87357, "tolerated": 77, "by_response_time": { "under125": 70521, "under250": 71126, "under500": 87357, "under1000": 87422, "under2000": 87434, "under4000": 87438 } }, "timings": { "redirect": 0, "namelookup": 9, "connection": 88, "handshake": 183, "response": 90, "total": 370 } }
disabled_locations[]=lan&disabled_locations[]=syd
recipients[]=email:12345&recipients[]=sms:67890
custom_headers[X-Api-Key]=xxxxxxxxx
curl -X POST -d 'url=:url' https://updown.io/api/checks?api-key=:apikey
{ "token": "ra6y", "url": "http://google.com", "alias": null, "last_status": null, "uptime": 100.0, "down": false, "down_since": null, "up_since": null, "error": null, "period": 60, "apdex_t": 0.5, "string_match": "", "enabled": true, "published": false, "disabled_locations": [], "recipients": ["email:1800216481", "slack:2734790322"], "last_check_at": null, "next_check_at": "2023-12-28T11:14:27Z", "created_at": "2023-12-28T11:13:27Z", "mute_until": null, "favicon_url": null, "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }
disabled_locations[]=lan&disabled_locations[]=syd
recipients[]=email:12345&recipients[]=sms:67890
custom_headers[X-Api-Key]=xxxxxxxxx
curl -X PUT https://updown.io/api/checks/:token?api-key=:apikey
{ "token": "ra6y", "url": "http://google.com", "alias": null, "last_status": null, "uptime": 100.0, "down": false, "down_since": null, "up_since": null, "error": null, "period": 60, "apdex_t": 0.5, "string_match": "", "enabled": true, "published": false, "disabled_locations": [], "recipients": ["email:1800216481", "slack:2734790322"], "last_check_at": null, "next_check_at": "2023-12-28T11:14:27Z", "created_at": "2023-12-28T11:13:27Z", "mute_until": null, "favicon_url": null, "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }
curl -X DELETE https://updown.io/api/checks/:token?api-key=:apikey
{ "deleted": true }
curl https://updown.io/api/nodes
{ "tok": { "ip": "45.76.104.117", "ip6": "2001:19f0:7001:45a::1", "city": "Tokyo", "country": "Japan", "country_code": "jp", "lat": 35.5833, "lng": 139.7483 } }
format
query param or using the corresponding mime-type in the Accept
header (application/json or text/plain).
curl https://updown.io/api/nodes/ips
[ "2001:19f0:6001:2c6::1", "45.32.74.41", "2001:19f0:9002:11a::1", "104.238.136.194", "2607:5300:60:4c2f::1", "192.99.37.47", "2001:41d0:2:85af::1", "91.121.222.175", "2001:19f0:6c01:145::1", "104.238.159.87", "2a01:4f9:c010:d5f9::1", "135.181.102.135", "2001:19f0:4400:402e::1", "45.32.107.181", "2001:19f0:7001:45a::1", "45.76.104.117", "2001:19f0:5801:1d8::1", "45.63.29.207", "2a01:4f8:141:441a::2", "178.63.21.176" ]
format
query param or using the corresponding mime-type in the Accept
header (application/json or text/plain).
curl https://updown.io/api/nodes/ipv4
45.32.74.41 104.238.136.194 192.99.37.47 91.121.222.175 104.238.159.87 135.181.102.135 45.32.107.181 45.76.104.117 45.63.29.207 178.63.21.176
format
query param or using the corresponding mime-type in the Accept
header (application/json or text/plain).
curl https://updown.io/api/nodes/ipv6
[ "2001:19f0:6001:2c6::1", "2001:19f0:9002:11a::1", "2607:5300:60:4c2f::1", "2001:41d0:2:85af::1", "2001:19f0:6c01:145::1", "2a01:4f9:c010:d5f9::1", "2001:19f0:4400:402e::1", "2001:19f0:7001:45a::1", "2001:19f0:5801:1d8::1", "2a01:4f8:141:441a::2" ]
The "id" attribute is the one you need to select recipients in the checks API.
The "immutable" attribute designates recipients which cannot be moved to another check after being created (currently only applies to statuspage.io integrations)
curl https://updown.io/api/recipients?api-key=:apikey
[ { "id": "email:3719031852", "type": "email", "name": "tech@example.com", "value": "Company <tech@example.com>" }, { "id": "sms:231178295", "type": "sms", "name": "+33123456789", "value": "+33123456789" }, { "id": "slack:2734790322", "type": "slack", "name": "mycompany#monitoring" }, { "id": "telegram:4147979801", "type": "telegram", "name": "Adrien Rey-Jarthon" }, { "id": "webhook:1159873859", "type": "webhook", "name": "My proxy", "value": "https://example.com/updown-endpoint" }, { "id": "zapier:2082375816", "type": "zapier", "name": "Send alerts to Teams" } ]
curl -X POST -d 'type=:type&value=:value' https://updown.io/api/recipients?api-key=:apikey
{ "id": "email:3719031852", "type": "email", "name": "tech@example.com", "value": "tech@example.com" }
curl -X DELETE https://updown.io/api/recipients/:id?api-key=:apikey
{ "deleted": true }
curl https://updown.io/api/status_pages?api-key=:apikey
[ { "token": "3ji4k", "url": "https://updown.io/p/3ji4k", "name": "Sample status page ✨", "description": "This is a demonstration status page from https://updown.io.\nYou can create and customize this kind of page for your own services.", "visibility": "public", "access_key": null, "checks": ["ngg8", "dmbe", "9e75", "l7ua", "6xjq", "wxax", "afha", "5yfe", "4osx", "1mjm", "sh6n", "5njh", "b1uc"] } ]
checks[]=dmbe&checks[]=ngg8
curl -X POST -d 'checks=:checks' https://updown.io/api/status_pages?api-key=:apikey
{ "token": "j4uqk", "url": "https://updown.io/p/j4uqk", "name": "My Page", "description": null, "visibility": "private", "access_key": null, "checks": [ "dmbe", "ngg8" ] }
checks[]=dmbe&checks[]=ngg8
curl -X PUT https://updown.io/api/status_pages/:token?api-key=:apikey
{ "token": "j4uqk", "url": "https://updown.io/p/j4uqk", "name": "My Page", "description": null, "visibility": "protected", "access_key": "8wFAy6pWkeVM3eca4TG71zN7N4tKcy", "checks": [ "dmbe", "ngg8" ] }
curl -X DELETE https://updown.io/api/status_pages/:token?api-key=:apikey
{ "deleted": true }
For the REST API parameters which accepts a time value, you have several accepted options including but not limited to:
2011-10-05T22:26:12-04:00
Wed, 05 Oct 2011 22:26:12 -0400
2010-10-31
(this would map to midnight UTC)
If you have another good looking time format you can try it out and see if it works. If you ommit the timezone it'll default to UTC. Please make sure these strings are properly URL encoded before sending them or you may get wrong results (ex %2B
instead of +
)
To setup a new webhook, all you have to do it go the your settings page and add the desired endpoint to the list of webhook URLs. Alternatively, you can use the REST API above to manage webhooks (/api/recipients
endpoint). You can add many endpoints, they'll all receive the same events. updown.io will send a POST request to all these endpoints every time an event occurs. Even though you'll often receive only one at a time, events will always be sent in an array, as we may send you multiple events in the same request in the future.
Your endpoint is supposed to respond with a HTTP 200 OK status (the body doesn't matter). Any other response will be considered an error and the webhook request will be retried up to 25 times across several days. You'll receive email warnings when your endpoint has been failing consistently for the last 10, 100 and 900 requests. After 1000 failed deliveries, the webhook endpoint will be automatically removed from your account.
Keep in mind that other events might be added at any time and you will start receiving them, so make sure your code accepts and ignores unknown events to be forward compatible.
All events include a description
attribute with a plain-text summary of the event, can be useful to easily implement notification forwarding proxies.
Once you have at least one endpoint configured, you can use this page to send a test webhook.
[{ "event": "check.down", "time": "2024-12-09T07:08:50Z", "description": "DOWN: https://updown.io/ since 06:58:50 (UTC), reason: 418 I'm a teapot", "check": { "token": "xyz0", "url": "https://updown.io", "alias": null, "last_status": 418, "uptime": 100.0, "down": true, "down_since": "2024-12-09T07:03:50Z", "up_since": null, "error": "418 I'm a teapot", "period": 30, "apdex_t": 0.25, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": [], "last_check_at": "2024-12-09T07:08:35Z", "next_check_at": "2024-12-09T07:09:05Z", "created_at": null, "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }, "downtime": { "id": "675697826ed64dfc1f2c61ba", "details_url": "https://updown.io/downtimes/675697826ed64dfc1f2c61ba", "error": "418 I'm a teapot", "started_at": "2024-12-09T06:58:50Z", "ended_at": null, "duration": null, "partial": null } }]
[{ "event": "check.up", "time": "2024-12-09T07:08:50Z", "description": "UP: https://updown.io/ since 07:08:35 (UTC), after being down for 10 minutes, reason: 418 I'm a teapot", "check": { "token": "xyz0", "url": "https://updown.io", "alias": null, "last_status": 200, "uptime": 100, "down": false, "down_since": null, "up_since": "2024-11-09T07:08:50Z", "error": null, "period": 30, "apdex_t": 0.25, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": [], "last_check_at": "2024-12-09T07:08:35Z", "next_check_at": "2024-12-09T07:09:05Z", "created_at": null, "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }, "downtime": { "id": "675697826ed64dfc1f2c61bc", "details_url": "https://updown.io/downtimes/675697826ed64dfc1f2c61bc", "error": "418 I'm a teapot", "started_at": "2024-12-09T06:58:50Z", "ended_at": "2024-12-09T07:08:35Z", "duration": 585, "partial": null } }]
[{ "event": "check.ssl_invalid", "time": "2024-12-09T07:08:50Z", "description": "The SSL certificate served by updown.io is not valid (error code 20: unable to get local issuer certificate)", "check": { "token": "xyz0", "url": "https://updown.io", "alias": null, "last_status": 200, "uptime": 100, "down": false, "down_since": null, "up_since": "2024-11-09T07:08:50Z", "error": null, "period": 30, "apdex_t": 0.25, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": [], "last_check_at": "2024-12-09T07:08:35Z", "next_check_at": "2024-12-09T07:09:05Z", "created_at": null, "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }, "ssl": { "cert": { "subject": "updown.io", "issuer": "Let's Encrypt Authority X3 (Let's Encrypt)", "from": "2018-09-08T21:00:18Z", "to": "2018-12-07T21:00:18Z", "algorithm": "SHA-256 with RSA encryption" }, "error": "error code 20: unable to get local issuer certificate" } }]
[{ "event": "check.ssl_valid", "time": "2024-12-09T07:08:50Z", "description": "The SSL certificate served by updown.io is now valid", "check": { "token": "xyz0", "url": "https://updown.io", "alias": null, "last_status": 200, "uptime": 100, "down": false, "down_since": null, "up_since": "2024-11-09T07:08:50Z", "error": null, "period": 30, "apdex_t": 0.25, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": [], "last_check_at": "2024-12-09T07:08:35Z", "next_check_at": "2024-12-09T07:09:05Z", "created_at": null, "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }, "ssl": { "cert": { "subject": "updown.io", "issuer": "Let's Encrypt Authority X3 (Let's Encrypt)", "from": "2018-09-08T21:00:18Z", "to": "2018-12-07T21:00:18Z", "algorithm": "SHA-256 with RSA encryption" } } }]
[{ "event": "check.ssl_expiration", "time": "2024-12-09T07:08:50Z", "description": "The SSL certificate served by updown.io will expire in 7 days", "check": { "token": "xyz0", "url": "https://updown.io", "alias": null, "last_status": 200, "uptime": 100, "down": false, "down_since": null, "up_since": "2024-11-09T07:08:50Z", "error": null, "period": 30, "apdex_t": 0.25, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": [], "last_check_at": "2024-12-09T07:08:35Z", "next_check_at": "2024-12-09T07:09:05Z", "created_at": null, "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }, "ssl": { "cert": { "subject": "updown.io", "issuer": "Let's Encrypt Authority X3 (Let's Encrypt)", "from": "2018-09-08T21:00:18Z", "to": "2018-12-07T21:00:18Z", "algorithm": "SHA-256 with RSA encryption" }, "days_before_expiration": 7 } }]
[{ "event": "check.ssl_renewed", "time": "2024-12-09T07:08:50Z", "description": "The SSL certificate served by updown.io was renewed", "check": { "token": "xyz0", "url": "https://updown.io", "alias": null, "last_status": 200, "uptime": 100, "down": false, "down_since": null, "up_since": "2024-11-09T07:08:50Z", "error": null, "period": 30, "apdex_t": 0.25, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": [], "last_check_at": "2024-12-09T07:08:35Z", "next_check_at": "2024-12-09T07:09:05Z", "created_at": null, "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }, "ssl": { "new_cert": { "subject": "updown.io", "issuer": "Let's Encrypt Authority X3 (Let's Encrypt)", "from": "2018-09-08T21:00:18Z", "to": "2018-12-07T21:00:18Z", "algorithm": "SHA-256 with RSA encryption" }, "old_cert": { "subject": "updown.io", "issuer": "Let's Encrypt Authority X3 (Let's Encrypt)", "from": "2018-09-08T21:00:18Z", "to": "2018-12-07T21:00:18Z", "algorithm": "SHA-256 with RSA encryption" } } }]
[{ "event": "check.performance_drop", "time": "2024-12-09T07:08:50Z", "description": "Apdex of https://updown.io/ dropped 47%", "check": { "token": "xyz0", "url": "https://updown.io", "alias": null, "last_status": 200, "uptime": 100, "down": false, "down_since": null, "up_since": "2024-11-09T07:08:50Z", "error": null, "period": 30, "apdex_t": 0.25, "string_match": "", "enabled": true, "published": true, "disabled_locations": [], "recipients": [], "last_check_at": "2024-12-09T07:08:35Z", "next_check_at": "2024-12-09T07:09:05Z", "created_at": null, "mute_until": null, "favicon_url": "https://updown.io/favicon.png", "custom_headers": {}, "http_verb": "GET/HEAD", "http_body": "" }, "apdex_dropped": "47%", "last_metrics": { "2023-03-12T02:00:00Z": { "apdex": 0.975 }, "2023-03-12T03:00:00Z": { "apdex": 1 }, "2023-03-12T04:00:00Z": { "apdex": 0.98 }, "2023-03-12T05:00:00Z": { "apdex": 1 }, "2023-03-12T06:00:00Z": { "apdex": 1 }, "2023-03-12T07:00:00Z": { "apdex": 0.51 } } }]
We maintain some DNS records allowing you to easily automate some tasks like whitelisting our IPs in your firewall (supported by PFSense for example).
dig +short A ips.updown.io
45.32.107.181 91.121.222.175 192.99.37.47 45.63.29.207 104.238.136.194 45.32.74.41 104.238.159.87 45.76.104.117 178.63.21.176
dig +short AAAA ips.updown.io
2001:19f0:4400:402e::1 2607:5300:60:4c2f::1 2001:19f0:5801:1d8::1 2001:19f0:7001:45a::1 2001:19f0:9002:11a::1 2001:19f0:6c01:145::1 2001:41d0:2:85af::1 2001:19f0:6001:2c6::1 2a01:4f8:141:441a::2