Retrieving Custom Alerts

All Custom Alerts for a given project can be retrieved using the following call:

curl -X GET https://api.brandwatch.com/projects/{projectId}/alerts

Where {projectID} is replaced with the ID of the Project containing the Alerts to be retrieved. (Click here to learn how to get your Project ID)

Optional Parameters

These optional parameters can be used when retrieving Alerts:

Note: at the time of writing these parameters only function when pagination parameters are included.

Parameter	Definition	Accepted Values	Default Value
search	A full or partial Alert name which can be used to filter Alerts	A string	""
enabled	Filter Alerts by whether they are paused	A boolean	false
owned	Filter Alerts by those created by your user (false will return all Alerts created by your user and others in the project)	A boolean	false

Pagination

You can control the pagination by passing the following additional parameters:

Parameter	Definition	Accepted Values	Default Value
`pageSize`	The number of Alerts on each page of the response	An integer, index starting at 1	All
`page`	The page to retrieve, indexed from 0	An integer, index starting at 0	0

Example Call

An example call to retrieve a paginated list of unpaused Alerts in the Project with ID 289733322 which all belong to the current user can be found below:

curl -X GET https://api.brandwatch.com/projects/289733322/alerts?search=Brandwatch&enabled=true&owned=true&pageSize=20&page=0

An example response can be found below:

{
  "resultsTotal": 2,
  "resultsPage": 0,
  "resultsPageSize": 20,
  "results": [
    {
      "id": 2046442302,
      "name": "Example Custom Alert 1",
      "queryId": 2002088770,
      "queryName": "Example Query 1",
      "userId": 2343208615,
      "clientId": 1357396178,
      "projectId": 289343322,
      "searchLiteString": "",
      "lastResourceId": 0,
      "lastAddedDate": "2024-11-17T23:02:56.435+0000",
      "enabled": true,
      "deleted": false,
      "frequency": 1440,
      "repeatOnDayOfWeek": 1,
      "repeatOnHourOfDay": 9,
      "created": "2024-09-23T14:23:50.594+0000",
      "nextRun": "2024-11-18T23:00:00.795+0000",
      "mentionsPerAlert": 5,
      "externalLink": false,
      "alertTypes": [
        "scheduled",
        "threshold"
      ],
      "threshold": null,
      "thresholdPercentage": null,
      "thresholdVolume": 100,
      "thresholdMode": "today",
      "thresholdIntervalMinutes": null,
      "thresholdStandardDeviations": null,
      "additionalRecipients": [
        {
          "recipient": "[email protected]",
          "accepted": true,
          "unsubscribed": false,
          "invited": true,
          "alertId": 2046442302
        }
      ],
      "emailCreator": true,
      "filter": {
        "queryId": [
          2002088770
        ]
      },
      "modifierId": 2233208615,
      "modifiedBy": "[email protected]",
      "lastModified": "2024-11-18T11:58:13.795407Z",
      "createdBy": "[email protected]"
    },
    {
      "id": 2046442302,
      "name": "Example Custom Alert 2",
      "queryId": 2102088770,
      "queryName": "Example Query 2",
      "userId": 2343208615,
      "clientId": 1357396178,
      "projectId": 289343322,
      "searchLiteString": "",
      "lastResourceId": 0,
      "lastAddedDate": "2024-11-18T10:05:59.141+0000",
      "enabled": true,
      "deleted": false,
      "frequency": 5,
      "repeatOnDayOfWeek": null,
      "repeatOnHourOfDay": 10,
      "created": "2024-09-09T15:30:43.510+0000",
      "nextRun": "2024-11-19T10:00:00.214+0000",
      "mentionsPerAlert": 25,
      "externalLink": false,
      "alertTypes": [
        "threshold"
      ],
      "threshold": 2,
      "thresholdPercentage": 200,
      "thresholdVolume": null,
      "thresholdMode": "today",
      "thresholdIntervalMinutes": null,
      "thresholdStandardDeviations": null,
      "additionalRecipients": [],
      "emailCreator": true,
      "filter": {
        "queryId": [
          2102088770
        ]
      },
      "modifierId": 2233208615,
      "modifiedBy": "[email protected]",
      "lastModified": "2024-11-18T11:58:13.795407Z",
      "createdBy": "[email protected]"
    },
  ]
}

In this particular the example the first Custom Alert is configured to send a scheduled and volume threshold alert ("alertTypes": ["scheduled", "threshold"]) such that the threshold Custom Alert email will be sent every Monday at 9 AM UTC ("repeatOnDayOfWeek": 1 and "repeatOnHourOfDay": 9) and if the number of mentions the specified query has picked up exceeds 100 ("thresholdVolume": 100). The scheduled Custom Alert email will be sent with a frequency of every 1440 minutes (daily).

The second Custom Alert in this example is similarly configured to send a threshold percentage Custom Alert email when the percentage of mentions is 200% greater than the average mention volume for the past 7 days ("thresholdPercentage": 200). As scheduled is not included in alertTypesthe value of frequency will be ignored.

Once you have the id of a Custom Alert it can be retrieved alone using the call below:

curl -X GET https://api.brandwatch.com/projects/{projectId}/alerts/{alertId}

where {alertId} is the id of the Custom Alert you wish to retrieve