Updating Custom Alerts

A Custom Alert can be updated using the following call:

curl -X PUT https://api.brandwatch.com/projects/{projectId}/alerts/{alertId}
-H 'Content-Type: application/json' \
-d '{
  "id": 2046442302,
	"name": "Example Updated Custom Alert",
	"queryId": 2002088770,
	"frequency": 5,
	"alertTypes": ["threshold, scheduled"],
	"repeatOnDayOfWeek": 1,
	"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) and {alertId} is the ID of the Custom Alert to be updated (Click here to learn how to get Custom Alert IDs). The body provided gives an example of the fields which can be used to configure a Custom Alert which are detailed below (click here for a more thorough explanation of Custom Alert configuration).

An example response for this call is shown below:

{
  "id": 2046442302,
  "name": "Example Updated 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 updating a Custom Alert and may be modified to update their value where stated:

Parameter	Definition	Accepted Values	Modifiable
`id`	The ID of the Custom Alert	ID returned from creation or retrieval endpoints	no
`name`	Name of the custom alert	string. Must be a unique Custom Alert name within the project	yes
`queryId`	The ID of the query which the Custom Alert will run on	integer (Click here to learn how to get Query IDs)	yes
`frequency`	How often a `scheduled` alert is triggered 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)	yes
`alertTypes`	How the Custom Alert is triggered	array containing either or both of `threshold` and`scheduled`	yes
`additionalRecipients`	Email addresses other than the creator's address 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	yes
`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	yes

Optional Fields

These optional fields can also be modified. All optional fields default to their current value:

Parameter	Definition	Accepted Values
`enabled`	Pause the Custom Alert when set to true	boolean
`mentionsPerAlert`	The number of mentions to display in the Custom Alert email	integer between 0 and 50
`repeatOnDayOfWeek`	Which day of the week a `thresholdVolume` Custom Alert is triggered on	integer between 1 and 7 (where 1 is Monday)
`repeatOnHourOfDay`	Which hours of the day a `thresholdVolume` Custom Alert is triggered on	integer between 0 and 23
`thresholdVolume`	The mention volume increase necessary for the Custom Alert to trigger *	integer
`thresholdPercentage`	The percentage of mention volume increase necessary for the Custom Alert to trigger *	integer

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