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 an 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.

value
number

The numeric threshold or percentage change. Required for threshold and relative alerts.

string_value
string

An alternative to value for string-based threshold alerts.

check_period
required integer

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

confirmation_period
required integer

The duration in seconds that a condition must be met before an alert is triggered. 0 for immediate triggering.

paused
boolean

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

escalation_target
object

An object defining where to send notifications. Can be the current team, another team, or an escalation policy.

metadata
object

A key-value object for custom metadata to be included in incidents.

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.

Escalation Targets

The escalation_target object determines where notifications are sent: - To use the current team, provide the string "current_team". - To target another team, use { "team_id": 123 } or { "team_name": "Ops Team" }. - To use an escalation policy, use { "policy_id": 456 } or { "policy_name": "Critical Policy" }.

Example Request

cURL
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" }
  }'


Previous article

Get a single dashboard alert

Next article

Update an dashboard alert