Get all existing monitor blackouts and recipient blackouts optionally filtered by type or associated monitor or recipient. The results include both future and past blackouts.
Request URL
GET https://api.alertsite.com/api/v3/blackouts[?parameters]
Authentication
The request must include the Authorization header containing a user’s access token:
Authorization: Bearer ACCESS_TOKEN
See Authentication for more information.
Query parameters
Query parameters are optional, but can be used to filter the returned data.
type
Filter the returned blackouts by type:
-
Monitor– monitor blackouts that disable monitoring -
Alert– monitor blackouts that disable alerting -
Notifier– recipient blackouts
If omitted, the operation returns all blackout types.
assoc_id
Integer. Optional monitor ID or recipient ID. If specified, returns only blackouts for this monitor or recipient.
persistent
Boolean. Use true to get only the recurring (persistent) blackouts, or false (default) to get both one-time and persistent blackouts.
limit
Integer. The maximum number of results to return. Use together with offset to paginate through a large number of results.
offset
Integer. Return the results starting from this offset (0-based).
select
String. A comma-separated list of data fields to return in the response. The field names are case-sensitive. Unrecognized field names are ignored.
If this parameter is omitted, all fields are included. Note that select= with an empty value is not the same as an omitted parameter, and means no fields will be returned.
For more information, see Filter response fields.
For a list of field names that can be used in the select parameter, see Blackout Object.
Response body
On success, the operation returns HTTP status 200 and a JSON object containing metadata and results, where results is an array of Blackout objects.
{
"metadata": {
"__permissions": {
"acl": 7
},
"resultset": {
"count": 2,
"limit": null,
"offset": "0"
}
},
"results": [
{
"assoc_id": 89561,
"date_added": null,
"end_day": null,
"end_time": null,
"from_date": "2017-11-28 14:40:00",
"id": 101441,
"login": null,
"note": null,
"persistent": false,
"start_day": null,
"start_time": null,
"thru_date": "2017-12-07 14:40:00",
"type": "Notifier"
},
{
"assoc_id": 135982,
"date_added": null,
"end_day": 7,
"end_time": "22:15",
"from_date": null,
"id": 105129,
"login": null,
"note": "Scheduled maintenance",
"persistent": true,
"start_day": 7,
"start_time": "20:00",
"thru_date": null,
"type": "Monitor"
}
]
}
If no blackouts matching the specified criteria are found, an empty results array is returned:
{
"metadata": {
"__permissions": {
"acl": 7
},
"resultset": {
"count": 0,
"limit": null,
"offset": "0"
}
},
"results": []
}
Error responses have HTTP status codes in the 4xx range.
Try it out
Click here to test this operation in AlertSite’s interactive API console.
Code examples
cURL
Get all blackouts:
curl https://api.alertsite.com/api/v3/blackouts -H "Authorization: Bearer ACCESS_TOKEN"
Get all persistent blackouts:
curl https://api.alertsite.com/api/v3/blackouts?persistent=true -H "Authorization: Bearer ACCESS_TOKEN"
Get persistent blackouts for monitor # 123456:
curl https://api.alertsite.com/api/v3/blackouts?assoc_id=123456&persistent=true -H "Authorization: Bearer ACCESS_TOKEN"
Get just the blackout IDs, types and IDs of associated monitors or recipients:
curl https://api.alertsite.com/api/v3/blackouts?select=id,type,assoc_id -H "Authorization: Bearer ACCESS_TOKEN"
Python
This example prints a list of all existing monitor and recipient blackouts.
Python
# Python 3.5+
import requests # Requests library http://docs.python-requests.org
import json
baseUrl = 'https://api.alertsite.com/api/v3'
username = '[email protected]' # Replace with your AlertSite login email
password = 'pa55w0rd' # Replace with your AlertSite password
# Log in
payload = {'username': username, 'password': password}
r = requests.post(baseUrl + '/access-tokens', data=json.dumps(payload), headers={'Content-Type': 'application/json'})
token = r.json()['access_token']
# Get all monitor and recipient blackouts
r = requests.get(baseUrl + '/blackouts', headers={'Authorization': 'Bearer ' + token})
result = r.json()
if r.status_code == requests.codes.ok:
blackouts = result['results']
print('Total blackouts found:', len(blackouts))
monitor_blackouts = [blackout for blackout in blackouts if blackout['type'] in ('Monitor', 'Alert')]
if monitor_blackouts:
print('Monitor blackouts:', *monitor_blackouts, sep='\n')
recipient_blackouts = [blackout for blackout in blackouts if blackout['type'] == 'Notifier']
if recipient_blackouts:
print('Recipient blackouts:', *recipient_blackouts, sep='\n')
else:
print('Could not get blackouts. The following error(s) occurred:', *result['errors'],
sep='\n')