# Update a dashboard alert

Updates an existing alert on a dashboard chart. You only need to provide the fields you want to change.

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/dashboards/{dashboard_id}/charts/{chart_id}/alerts/{id}"
method = "PATCH"

[[path_param]]
name = "dashboard_id"
description = "The unique identifier of the dashboard."
required = true
type = "integer"

[[path_param]]
name = "chart_id"
description = "The unique identifier of the chart."
required = true
type = "integer"

[[path_param]]
name = "id"
description = "The unique identifier of the alert to update."
required = true
type = "integer"

[[body_param]]
name = "name"
description = "A new name for the alert."
required = false
type = "string"

[[body_param]]
name = "alert_type"
description = "The type of alert. `threshold` for static values, `relative` for percentage changes, or `anomaly_rrcf` for ML-based anomaly detection. Cannot be changed after creation."
required = false
type = "string"

[[body_param]]
name = "operator"
description = "The comparison operator. Required for `threshold` and `relative` alerts. For `threshold`: `equal`, `not_equal`, `higher_than`, `higher_than_or_equal`, `lower_than`, `lower_than_or_equal`. For `relative`: `increases_by`, `decreases_by`, `changes_by`. Not used for `anomaly_rrcf` alerts."
required = false
type = "string"

[[body_param]]
name = "value"
description = "The numeric value for the alert condition. For `threshold` alerts, this is the static threshold. For `relative` alerts, this is the percentage change. Required for `threshold` and `relative` types unless `string_value` is set. A value of `0` is valid."
required = false
type = "number"

[[body_param]]
name = "string_value"
description = "An alternative to `value` for `threshold` alerts when matching an exact string. If `string_value` is set, `value` is not required. Only valid with `equal` or `not_equal` operators."
required = false
type = "string"

[[body_param]]
name = "check_period"
description = "How often to evaluate the alert condition, in seconds. Required for `threshold` and `relative` alert types. Not used for `anomaly_rrcf` alerts."
required = false
type = "integer"

[[body_param]]
name = "query_period"
description = "The time window in seconds for the data being analyzed. If not provided, falls back to `aggregation_interval`, then `check_period`."
required = false
type = "integer"

[[body_param]]
name = "aggregation_interval"
description = "The size of data buckets in seconds for aggregating and evaluating the metric. If not provided, falls back to `query_period`, then `check_period`."
required = false
type = "integer"

[[body_param]]
name = "confirmation_period"
description = "The duration in seconds that a condition must be met before an alert is triggered. A value of `0` triggers the alert immediately."
required = false
type = "integer"

[[body_param]]
name = "recovery_period"
description = "The duration in seconds that a condition must be resolved before an incident is recovered."
required = false
type = "integer"

[[body_param]]
name = "anomaly_sensitivity"
description = "The sensitivity of the anomaly detection model, from 0 to 100. Higher values result in more alerts. Only for `anomaly_rrcf` alerts."
required = false
type = "number"

[[body_param]]
name = "anomaly_trigger"
description = "Defines which anomalies trigger an alert: `any` (both higher and lower), `higher`, or `lower`. Only for `anomaly_rrcf` alerts."
required = false
type = "string"

[[body_param]]
name = "series_names"
description = "An array of strings to filter the alert to specific data series."
required = false
type = "array"

[[body_param]]
name = "source_variable"
description = "The variable name for the source selection. If not provided, derived automatically from the dashboard preset's source variable."
required = false
type = "string"

[[body_param]]
name = "source_mode"
description = "The mode for source selection. Valid values: `source_variable`, `platforms_single_source`, `platforms_all_sources`."
required = false
type = "string"

[[body_param]]
name = "source_platforms"
description = "An array of platform names to filter the sources this alert runs on."
required = false
type = "array"

[[body_param]]
name = "incident_cause"
description = "A custom description template for the incident created by this alert. Supports `{{value}}` placeholder."
required = false
type = "string"

[[body_param]]
name = "incident_per_series"
description = "Whether a separate incident will be created for each data series that triggers the alert."
required = false
type = "boolean"

[[body_param]]
name = "escalation_target"
description = "Defines where to send notifications. Defaults to `current_team`."
required = false
type = "object"

[[body_param]]
name = "call"
description = "Enable phone call notifications. Only used if `escalation_target` is not a policy."
required = false
type = "boolean"

[[body_param]]
name = "sms"
description = "Enable SMS notifications. Only used if `escalation_target` is not a policy."
required = false
type = "boolean"

[[body_param]]
name = "email"
description = "Enable email notifications. Only used if `escalation_target` is not a policy."
required = false
type = "boolean"

[[body_param]]
name = "push"
description = "Enable push notifications. Only used if `escalation_target` is not a policy."
required = false
type = "boolean"

[[body_param]]
name = "critical_alert"
description = "Enable critical push notifications that bypass Do Not Disturb. Only used if `escalation_target` is not a policy."
required = false
type = "boolean"

[[body_param]]
name = "metadata"
description = "A key-value object for custom metadata to be included in incidents. Both keys and values must be strings. This will replace all existing metadata."
required = false
type = "object"

[[body_param]]
name = "paused"
description = "Whether the alert should be paused or active."
required = false
type = "boolean"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = "The alert was updated successfully."
body = '''
{
  "data": {
    "id": "789",
    "type": "alert",
    "attributes": {
      "name": "Updated Alert Name",
      "value": 150.0
    }
  }
}
'''

[[response]]
status = 404
description = "The specified dashboard, chart, or alert was not found."
[/responses]

[info]
Updating the `metadata` object will replace the entire object, not merge it. Any keys not included in the update request will be removed.
[/info]

## Example request

```shell
[label cURL]
curl --request PATCH \
  --url https://telemetry.betterstack.com/api/v2/dashboards/123/charts/456/alerts/789 \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Updated Alert Name",
    "value": 150.0
  }'
```