Creating Custom Alerts

A Custom Alert can be created for a given project using the following call:

curl -X POST https://api.brandwatch.com/projects/{projectId}/alerts
-H 'Content-Type: application/json' \
-d '{
	"name": "Example Custom Alert",
	"queryId": 2002088770,
	"projectId": 289343322,
	"frequency": 5,
	"alertTypes": ["threshold, scheduled"],
	"repeatOnHourOfDay": 9,
	"thresholdVolume": 100,
  "thresholdPercentage": null,
	"additionalRecipients": [],
	"filter": {}
}'

Where {projectID} is replaced with the ID of the given Project. (Click here to learn how to get your Project ID). The body provided gives an example of the minimum required fields which are detailed below.

An example response for this call is shown below (click here for a more thorough explanation of Custom Alert configuration):

{
  "id": 2046442302,
  "name": "Example Custom Alert",
  "queryId": 2002088770,
  "queryName": "Example Query",
  "userId": 2343208615,
  "clientId": 1357396178,
  "projectId": 289343322,
  "searchLiteString": "",
  "lastResourceId": 0,
  "lastAddedDate": "2025-02-18T15:38:53.596+0000",
  "enabled": true,
  "deleted": false,
  "frequency": 5,
  "repeatOnDayOfWeek": null,
  "repeatOnHourOfDay": null,
  "created": "2025-02-18T15:38:53.596+0000",
  "nextRun": "2025-02-18T15:38:53.596+0000",
  "mentionsPerAlert": 5,
  "externalLink": false,
  "alertTypes": [
    "threshold"
  ],
  "threshold": null,
  "thresholdPercentage": null,
  "thresholdVolume": 100,
  "thresholdMode": "today",
  "thresholdIntervalMinutes": null,
  "thresholdStandardDeviations": null,
  "additionalRecipients": [],
  "emailCreator": true,
  "filter": {
    "queryId": [
      2002088770
    ]
  },
  "modifierId": 2033208615,
  "modifiedBy": "[email protected]",
  "lastModified": "2025-02-18T15:38:53.596+0000",
  "createdBy": "[email protected]"
}

Required Fields

These fields must be included when creating a Custom Alert:

Parameter	Definition	Accepted Values
`name`	Name of the custom alert	string. Must be a unique Custom Alert name within the project
`queryId`	The ID of the query which the Custom Alert will run on	integer (Click here to learn how to get Query IDs)
`frequency`	How often a `scheduled` alert is sent in minutes	integer. Valid values are 5, 15, 30, 60, 720, 1440, 10080 (these values map to the UI values of "as it happens", 5 - 60 minutes, twice daily, daily, and weekly)
`alertTypes`	How the Custom Alert is triggered	array containing either or both of `threshold` and`scheduled`
`repeatOnHourOfDay`	Which hours of the day a `thresholdVolume` Custom Alert is triggered on	integer between 0 and 23. Required for `thresholdVolume` Custom Alerts
`thresholdVolume`	The mention volume increase necessary for the Custom Alert to trigger *	integer. One of `thresholdVolume` or `thresholdPercentage` is required for `threshold` Custom Alerts
`thresholdPercentage`	The percentage of mention volume increase necessary for the Custom Alert to trigger *	integer. One of `thresholdVolume` or `thresholdPercentage` is required for `threshold` Custom Alerts
`additionalRecipients`	Email addresses other than the creator's address which the Custom Alert emails should be sent to	array of strings containing valid email addresses. Required but can be empty if no additional email addresses are needed
`filter`	Filters which can be used to further filter the mentions picked up by the Custom Alert	object containing filters (Click here to learn more about Filters). Required but can be empty if no filters are needed

* When creating a threshold Custom Alert you can include thresholdVolume or thresholdPercentage. Including both will result in thresholdPercentage being ignored.

Optional Fields

Parameter	Definition	Accepted Values	Default Value
`mentionsPerAlert`	The number of mentions to display in the Custom Alert email	integer between 0 and 50	5
`repeatOnDayOfWeek`	Which day of the week a `thresholdVolume` Custom Alert is triggered on	integer between 1 and 7 (where 1 is Monday). Not required for `thresholdVolume` Custom Alerts but can be used to trigger them on specific days only	null