Update an alert

Updates an existing alert by its ID. You only need to provide the fields you want to change.

{
  "data": {
    "id": "789",
    "type": "alert",
    "attributes": {
      "name": "High Error Rate Alert",
      "alert_type": "threshold",
      "operator": "higher_than",
      "value": 150.0,
      "query_period": 300,
      "confirmation_period": 60,
      "recovery_period": 300,
      "escalation_target": {
        "policy_id": 123,
        "policy_name": "Critical Alerts Policy"
      },
      "paused": false,
      "paused_reason": null,
      "created_at": "2026-02-20T10:00:00Z",
      "updated_at": "2026-02-24T15:00:00Z"
    }
  }
}

Example request

curl --request PATCH \
  --url https://telemetry.betterstack.com/api/v2/alerts/789 \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "value": 150.0,
    "confirmation_period": 60
  }'

Escalation targets

The escalation_target object determines where notifications are sent:

• For current team, use "current_team" as a string.

• Reference a different team using { "team_id": 123 } or { "team_name": "Ops Team" }.

• Reference an escalation policy using { "policy_id": 456 } or { "policy_name": "Critical Policy" }. When escalating to a policy, notification channels (call, sms, etc.) are managed by the policy itself and are ignored in the API request.

Metadata

The metadata object allows you to attach custom key-value pairs to an alert. This information is included in incident notifications for extra context. Both keys and values must be strings.

All alert metadata will be overwritten when the metadata field is used. Ommited keys will be removed.

{
  "metadata": {
    "environment": "production",
    "runbook": "https://wiki.example.com/runbooks/high-error-rate"
  }
}