Alarms API reference

The Alarms API lets you programmatically manage Insights alarms. All alarm endpoints are scoped to a project.

Notification channels for alarms are managed in the Honeybadger UI and can’t be set via the API.

Get an alarm list or alarm details

curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/alarms
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/alarms/ID

The list endpoint returns results in a results array. The detail endpoint returns a single alarm:

{
  "id": "8f0dc2b1-4d9e-4b6a-9c3f-2e7a51d0c8aa",
  "name": "High error rate",
  "description": "Triggers when error count exceeds 100 in 5 minutes",
  "state": "ok",
  "query": "filter event_type::str == \"notice\"",
  "stream_ids": ["9c1e5b7a-1f2d-4e3c-8a9b-0d6f4c2e1a5b"],
  "evaluation_period": "5m",
  "lookback_lag": "1m",
  "trigger_config": {
    "type": "alert_result_count",
    "config": { "operator": "gt", "value": 100 }
  },
  "error": null,
  "last_checked_at": "2026-02-04T09:10:00Z",
  "next_check_at": "2026-02-04T09:15:00Z",
  "created_at": "2026-01-31T14:22:18Z",
  "updated_at": "2026-02-04T09:11:05Z",
  "url": "https://app.honeybadger.io/projects/1/insights/alarms/42",
  "project_id": 1
}

The response includes:

Field name	Type	Description
id	string	The alarm’s UUID. Use this value in URLs for show, update, delete, and history requests.
name	string	The alarm name.
description	string	The alarm description.
state	string	The alarm’s current state: "ok" (trigger condition not met), "alarm" (triggered), or "initial" (not yet evaluated).
query	string	The BadgerQL query the alarm evaluates.
stream_ids	array	The IDs of the Insights streams the alarm queries.
evaluation_period	string	How often the alarm is evaluated, as a duration string ("5m", "1h", "1d").
lookback_lag	string	The delay before each evaluation to allow data to arrive ("1m", "0s").
trigger_config	object	The trigger condition. See Trigger config.
error	string	The error message if the alarm’s query failed to execute; null otherwise.
last_checked_at	string	ISO 8601 timestamp of the last evaluation.
next_check_at	string	ISO 8601 timestamp of the next scheduled evaluation.
created_at	string	ISO 8601 timestamp.
updated_at	string	ISO 8601 timestamp.
url	string	A link to the alarm in the Honeybadger UI.
project_id	integer	The project the alarm belongs to.

Create an alarm

curl -u AUTH_TOKEN: \
  -X POST \
  -H 'Content-type: application/json' \
  -d '{
    "alarm": {
      "name": "High error rate",
      "description": "Triggers when error count exceeds 100 in 5 minutes",
      "query": "filter event_type::str == \"notice\"",
      "evaluation_period": "5m",
      "lookback_lag": "1m",
      "trigger_config": {
        "type": "alert_result_count",
        "config": { "operator": "gt", "value": 100 }
      }
    }
  }' \
  https://app.honeybadger.io/v2/projects/ID/alarms

Returns 201 Created with the alarm JSON shown above.

The request body must be wrapped in a top-level alarm object. These fields can be provided:

Field name	Type	Description
name	string	Required. The alarm name.
query	string	Required. A BadgerQL query that returns the data to monitor. The alarm system wraps the query to count matching results per evaluation period, so a bare filter works — see Query guidelines below.
evaluation_period	string	Required. How often the alarm is evaluated, as a duration string ("5m", "1h", "1d"). Minimum 1m, maximum less than a week.
trigger_config	object	Required. The condition that triggers the alarm. See Trigger config.
description	string	Optional description.
stream_ids	array	Optional list of Insights stream IDs to query. Defaults to all streams on the project. IDs that don’t belong to the project are ignored.
lookback_lag	string	Optional delay before each evaluation to allow data to arrive ("1m", "0s").

A 422 Unprocessable Entity response with an errors key is returned when the alarm is invalid — for example, a missing required field, an invalid BadgerQL query, or an unknown trigger type.

Trigger config

The trigger_config object defines when the alarm transitions to the alarm state:

Field name	Type	Description
type	string	The trigger type. Currently "alert_result_count", which triggers based on the count of results returned by the query.
config.operator	string	The comparison operator: "gt", "gte", "lt", "lte", "eq", or "neq".
config.value	integer	The threshold to compare the result count against. Must be >= 0.

Some examples:

// Trigger when more than 50 events match the query
{ "type": "alert_result_count", "config": { "operator": "gt", "value": 50 } }

// Trigger when no events match (e.g., a missing heartbeat)
{ "type": "alert_result_count", "config": { "operator": "eq", "value": 0 } }

// Trigger when any events match
{ "type": "alert_result_count", "config": { "operator": "neq", "value": 0 } }

Query guidelines

The alarm system automatically wraps the query to count results per evaluation period, so the query should filter and/or aggregate events, and the system handles the final counting:

filter event_type::str == "notice"
filter status::int >= 500
filter event_type::str == "request.handled" and duration::int > 5000

Queries with stats also work — the system counts the result rows:

filter event_type::str == "notice" | stats count() as count by fault_id::int

Update an alarm

curl -u AUTH_TOKEN: \
  -X PUT \
  -H 'Content-type: application/json' \
  -d '{
    "alarm": {
      "name": "High error rate",
      "query": "filter event_type::str == \"notice\"",
      "evaluation_period": "10m",
      "trigger_config": {
        "type": "alert_result_count",
        "config": { "operator": "gt", "value": 100 }
      }
    }
  }' \
  https://app.honeybadger.io/v2/projects/ID/alarms/ID

Returns 204 No Content on success. The request body uses the same fields as Create an alarm. The submitted definition replaces the existing one, so include every field — even the ones you aren’t changing.

Delete an alarm

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/alarms/ID

Returns 204 No Content on success.

Get alarm trigger history

curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/alarms/ID/history

Returns the alarm’s past evaluations that changed its state:

{
  "triggers": [
    {
      "id": "d4c8a2f6-3b1e-4f7a-8c5d-9e0b2a6f1c3e",
      "state": "alarm",
      "result": { "count": 127 },
      "created_at": "2026-02-04T09:05:00Z"
    }
  ],
  "links": {
    "self": "...",
    "prev": "...",
    "next": "..."
  }
}

Each entry in the triggers array includes:

Field name	Type	Description
id	string	The trigger event ID.
state	string	The state after the evaluation: "ok", "alarm", or "error".
result	object	The query result that caused the state change.
created_at	string	ISO 8601 timestamp of the evaluation.

Use the page query parameter to paginate; the links object contains URLs for the previous and next pages.