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 API
    3. Source groups API
    4. Metrics API
    5. Dashboards API
    6. Explorations API
    7. Exploration groups API
    8. Alerts API
      1. List alerts in exploration GET
      2. Get a single alert GET
      3. Create an alert POST
      4. Update an alert PATCH
      5. Remove an alert DELETE
    9. Connections API
    10. Collectors API
    11. Query API ↗
  7. Alternative to
    1. Lightstep

Create an alert

Creates a new alert for a specific exploration.

POST https://telemetry.betterstack.com/api/v2/explorations/{exploration_id}/alerts

URL parameters

exploration_id
required integer

The unique identifier of the exploration to add the alert to.

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, and 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. 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 ignored. Only for threshold alerts with equal or not_equal operators.

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.

query_period
integer

The time window in seconds for the data being analyzed.

confirmation_period
required integer

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

recovery_period
integer

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

check_period
integer

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

aggregation_interval
integer

The size of data buckets in seconds for aggregating and evaluating the metric.

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.

source_mode
string

The mode for source selection (e.g., source_variable).

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.

incident_per_series
boolean

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

escalation_target
object

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

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.

paused
boolean

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

team_name
string

Required if using a global API token to specify which team should own the resource.

201

The alert was created successfully.

Response body

{
  "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,
      "paused_reason": null,
      "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"
    }
  }
}
422

Validation failed, e.g., due to an incompatible exploration.

Response body

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

Alerts can only be created on explorations with compatible chart types: line_chart, bar_chart, number_chart, or tail_chart. The query must also include the {{time}} variable.

Example requests

Threshold alert Relative alert Anomaly alert 
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_type": "threshold",
    "operator": "higher_than",
    "value": 100,
    "confirmation_period": 0,
    "check_period": 300,
    "escalation_target": "current_team"
  }'
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/explorations/123/alerts \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Sign-ups Dropped",
    "alert_type": "relative",
    "operator": "decreases_by",
    "value": 50,
    "check_period": 600,
    "query_period": 3600,
    "escalation_target": { "team_name": "My team" }
  }'
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/explorations/123/alerts \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Anomalous CPU usage",
    "alert_type": "anomaly_rrcf",
    "confirmation_period": 0,
    "check_period": 900,
    "anomaly_sensitivity": 75,
    "anomaly_trigger": "higher",
    "escalation_target": { "policy_id": 456 }
  }'


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 alert

Next article

Update an alert