Creating Custom Alerts
Adding a new Custom Alert to your project
queryIdandqueryNameproperties are deprecatedThey will be removed on or after 12th January 2026. Any usages of
queryIdshould be replaced with thequeryIdsfield (see example below).queryNamehas no replacement.
Alert Limit addition
The number of alerts that are allowed to be created in any client will be limited in late 2025. The limits will depend on your account plan.
additionalRecipientsandemailCreatorare deprecated.Use the new
recipientsfield instead.additionalRecipientsandemailCreatorare still accepted and are still returned in responses (derived from recipients), so existing integrations keep working.Migration notes
- A request must provide exactly one of
recipientsoradditionalRecipients, sending both, or neither is rejected.- When you use
recipients,emailCreatoris ignored. To have the alert creator receive the alert, include the creator as an entry inrecipients.Deprecated fields will be removed on or after 16th November 2026
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",
"queryIds": [2002088770],
"projectId": 289343322,
"frequency": 5,
"alertTypes": ["threshold", "scheduled"],
"repeatOnHourOfDay": 9,
"thresholdVolume": 100,
"thresholdPercentage": null,
"recipients": [],
"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,
"queryIds": [
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": [],
"recipients": [],
"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 |
queryIds | The ID(s) of the query which the Custom Alert will run on | array of integers (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 andscheduled |
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 |
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 |
recipients | Email addresses including 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 |
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 |
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 |
* 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 |