Get Blackouts

Last modified on May 22, 2024

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



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.


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.


Integer. Optional monitor ID or recipient ID. If specified, returns only blackouts for this monitor or recipient.


Boolean. Use true to get only the recurring (persistent) blackouts, or false (default) to get both one-time and persistent blackouts.


Integer. The maximum number of results to return. Use together with offset to paginate through a large number of results.


Integer. Return the results starting from this offset (0-based).


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


Get all blackouts:

curl -H "Authorization: Bearer ACCESS_TOKEN"

Get all persistent blackouts:

curl -H "Authorization: Bearer ACCESS_TOKEN"

Get persistent blackouts for monitor # 123456:

curl -H "Authorization: Bearer ACCESS_TOKEN"

Get just the blackout IDs, types and IDs of associated monitors or recipients:

curl,type,assoc_id -H "Authorization: Bearer ACCESS_TOKEN"


This example prints a list of all existing monitor and recipient blackouts.


# Python 3.5+
import requests  # Requests library
import json

baseUrl = ''
username = '[email protected]'  # Replace with your AlertSite login email
password = 'pa55w0rd'          # Replace with your AlertSite password

# Log in
payload = {'username': username, 'password': password}
r = + '/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 ==
    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')
    print('Could not get blackouts. The following error(s) occurred:', *result['errors'],

See Also

Blackout Operations

Highlight search results