Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. metrics
  4. Ingesting data
    1. Better Stack collector
    2. Vector
    3. OpenTelemetry
    4. Ingesting via HTTP API
    5. Ingesting metrics
    6. Ingesting logs
    7. Migrating to Better Stack
  5. Using the product
    1. AI SRE ↗
    2. MCP server ↗
    3. Transforming ingested data
    4. Querying data
    5. Tracing
    6. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources & collectors
    3. Dashboards
      1. Dashboards API
      2. Charts API
      3. Dashboard sections API
      4. Dashboard alerts API
        1. List dashboard alerts GET
        2. Get a single alert GET
        3. Create an alert POST
        4. Update an alert PATCH
        5. Remove an alert DELETE
      5. Dashboard groups API
    4. Explorations
    5. Alerts API
    6. Connections API
    7. Query API ↗
  7. Alternative to
    1. Lightstep

Create a dashboard alert

Creates a new alert for a specific dashboard chart.

POST https://telemetry.betterstack.com/api/v2/dashboards/{dashboard_id}/charts/{chart_id}/alerts

URL parameters

dashboard_id
required integer

The unique identifier of the dashboard.

chart_id
required integer

The unique identifier of the chart.

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

name
required string

The name of the alert.

alert_type
required string

The type of alert. threshold for static values, relative for percentage changes, or anomaly_rrcf for ML-based anomaly detection.

operator
string

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.

value
number

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.

string_value
string

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.

check_period
required integer

How often to evaluate the alert condition, in seconds. Required for threshold and relative alert types. Not used for anomaly_rrcf alerts.

query_period
integer

The time window in seconds for the data being analyzed. If not provided, falls back to aggregation_interval, then check_period.

aggregation_interval
integer

The size of data buckets in seconds for aggregating and evaluating the metric. If not provided, falls back to query_period, then check_period.

confirmation_period
integer

The duration in seconds that a condition must be met before an alert is triggered. A value of 0 triggers the alert immediately. Default: 0.

recovery_period
integer

The duration in seconds that a condition must be resolved before an incident is recovered.

anomaly_sensitivity
number

The sensitivity of the anomaly detection model, from 0 to 100. Higher values result in more alerts. Only for anomaly_rrcf alerts.

anomaly_trigger
string

Defines which anomalies trigger an alert: any (both higher and lower), higher, or lower. Only for anomaly_rrcf alerts.

series_names
array

An array of strings to filter the alert to specific data series.

source_variable
string

The variable name for the source selection. If not provided, derived automatically from the dashboard preset's source variable.

source_mode
string

The mode for source selection. Valid values: source_variable, platforms_single_source, platforms_all_sources.

source_platforms
array

An array of platform names to filter the sources this alert runs on.

incident_cause
string

A custom description template for the incident created by this alert. Supports {{value}} placeholder.

incident_per_series
boolean

Whether a separate incident will be created for each data series that triggers the alert.

escalation_target
object

Defines where to send notifications. Defaults to current_team, for details see Escalation targets.

call
boolean

Enable phone call notifications. Only used if escalation_target is not a policy.

sms
boolean

Enable SMS notifications. Only used if escalation_target is not a policy.

email
boolean

Enable email notifications. Only used if escalation_target is not a policy.

push
boolean

Enable push notifications. Only used if escalation_target is not a policy.

critical_alert
boolean

Enable critical push notifications that bypass Do Not Disturb. Only used if escalation_target is not a policy.

metadata
object

A key-value object for custom metadata to be included in incidents. Both keys and values must be strings. For details, see Metadata.

paused
boolean

Set to true to create the alert in a paused state.

201

The alert was created successfully.

Response body

{
  "data": {
    "id": "790",
    "type": "alert",
    "attributes": {
      "name": "High Error Rate",
      "alert_type": "threshold",
      "operator": "higher_than",
      "value": 100.0,
      "paused": false
    }
  }
}
422

Validation failed, e.g., due to an incompatible chart type.

Response body

{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "chart_type": "Alerts are not supported for chart type 'pie_chart'."
  }
}

Alerts can only be created on charts with compatible types: line_chart, bar_chart, number_chart, tail_chart, or table_chart.

Example requests

Threshold alert String value alert 
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/dashboards/123/charts/456/alerts \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "High Error Rate",
    "alert_type": "threshold",
    "operator": "higher_than",
    "value": 100,
    "check_period": 300,
    "confirmation_period": 0,
    "escalation_target": { "policy_name": "Critical Policy" },
    "metadata": { "runbook": "http://runbook/high-errors" }
  }'
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/dashboards/123/charts/456/alerts \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Status is Error",
    "alert_type": "threshold",
    "operator": "equal",
    "string_value": "error",
    "check_period": 300,
    "confirmation_period": 0
  }'


Alert types and attributes

The attributes in the alert response vary based on the alert_type.

Threshold/Relative Response Anomaly Response 
{
  "operator": "higher_than",
  "value": 100,
  "string_value": null,
  "check_period": 300
}
{
  "anomaly_sensitivity": 75.0,
  "anomaly_trigger": "any"
}

For threshold and relative alerts, the fields anomaly_sensitivity and anomaly_trigger are omitted. For anomaly_rrcf alerts, the fields operator, value, string_value, and check_period are omitted.

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.

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

Previous article

Get a single dashboard alert

Next article

Update a dashboard alert