--- title: Alarms API reference description: API reference for managing Insights alarms with endpoints to create, read, update, and delete alarms and view their trigger history. url: https://docs.honeybadger.io/api/alarms/ --- The Alarms API lets you programmatically manage [Insights alarms](https://docs.honeybadger.io/guides/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 ```bash 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: ```json { "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](https://docs.honeybadger.io/guides/insights/badgerql/) 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](https://docs.honeybadger.io/api/alarms/#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 ```bash 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](https://docs.honeybadger.io/guides/insights/badgerql/) 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](https://docs.honeybadger.io/api/alarms/#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](https://docs.honeybadger.io/api/alarms/#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: ```json // 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: ```plaintext 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: ```plaintext filter event_type::str == "notice" | stats count() as count by fault_id::int ``` ## Update an alarm ```bash 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](https://docs.honeybadger.io/api/alarms/#create-an-alarm). The submitted definition replaces the existing one, so include every field — even the ones you aren’t changing. ## Delete an alarm ```bash 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 ```bash curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/alarms/ID/history ``` Returns the alarm’s past evaluations that changed its state: ```json { "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. --- ## Try Honeybadger for FREE Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice. [Start free trial](https://app.honeybadger.io/users/sign_up) [See plans and pricing](https://www.honeybadger.io/plans/)