Create an alert

Creates a new alert for a specific exploration.

{
  "data": {
    "id": 789,
    "type": "alert",
    "attributes": {
      "name": "High Error Rate Alert",
      "alert_type": "threshold",
      "operator": "higher_than",
      "value": 100.0,
      "query_period": 300,
      "confirmation_period": 0,
      "recovery_period": 300,
      "escalation_target": {
        "policy_id": 456
      },
      "paused": false,
      "incident_cause": "Error rate exceeded threshold",
      "metadata": {
        "environment": "production",
        "service": "api"
      },
      "created_at": "2026-02-20T10:00:00Z",
      "updated_at": "2026-02-20T10:00:00Z"
    }
  }
}

{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "name": [
      "can't be blank"
    ]
  }
}

Example Request

curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/explorations/123/alerts \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "High Error Rate Alert",
    "alert_type": "threshold",
    "operator": "higher_than",
    "value": 100.0,
    "query_period": 300,
    "confirmation_period": 0,
    "recovery_period": 300,
    "escalation_target": {
      "policy_id": 456
    },
    "incident_cause": "Error rate exceeded threshold",
    "metadata": {
      "environment": "production",
      "service": "api"
    }
  }'

Escalation Target

The escalation_target object determines where notifications are sent.

• Escalate to the current team (default): Set escalation_target to null.
• Escalate to a specific team: Use "escalation_target": { "team_id": 123 }.
• Escalate via an Uptime policy: Use "escalation_target": { "policy_id": 456 }. When using 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.

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

Alert Types

Operators

For threshold alerts: equal, not_equal, higher_than, higher_than_or_equal, lower_than, lower_than_or_equal

For relative alerts: increases_by, decreases_by, changes_by