Get Blackouts

Last modified on August 24, 2020

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 = 'demo@example.com'  # 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')

See Also

Blackout Operations

Highlight search results