---
title: "Create an alarm"
method: POST
path: "/projects/{project_id}/alarms"
tags: ["Alarms"]
---

# Create an alarm

`POST /projects/{project_id}/alarms`

## Request

- Base URL: `https://app.honeybadger.io/v3`
- URL: `https://app.honeybadger.io/v3/projects/{project_id}/alarms`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/honeybadger/apis/honeybadger-api/docs/projects/:project_id/alarms/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new alarm for the project.

## Path parameters

- `project_id` string, required

## Request body

- AlarmCreateInput: A new alarm
  - `name` string, required: Alarm name
  - `description` string, nullable: What the alarm watches for, shown with it in Honeybadger. Null clears it.
  - `query` string, required: BadgerQL evaluated on each check
  - `stream_ids` string[], nullable: Streams the query runs against. A set: order is ignored, duplicates are dropped, and it can't be empty. Left out or null, set to the project's current streams.
  - `evaluation_period` string, required: Window each evaluation covers. At least 1m and less than a week (`w` units are refused).
  - `lookback_lag` string, required: How far behind now the window ends, allowing for ingestion delay
  - `trigger_config` AlarmTriggerConfig, required: What turns the alarm on. Sent whole: on update, a `trigger_config` replaces the stored one rather than merging into it.
    - `type` 'alert_result_count', required: `alert_result_count` compares the number of results the query returns.
    - `config` AlarmTriggerCondition, required: The comparison against the query's result that fires the trigger
      - `operator` 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'neq', required: How the query's result is compared with `value`: greater than, greater than or equal, less than, less than or equal, equal, or not equal.
      - `value` number, double, required: Threshold to compare against. `alert_result_count` takes a whole number >= 0.

## Response `201`

Alarm created

- object
  - `data` Alarm, required: An Insights alarm: a BadgerQL query run on a schedule over a project's streams, which notifies its integrations when the result crosses the trigger.
    - `id` string, required
    - `project_id` string, required: ID of the project this alarm belongs to
    - `name` string, required: Alarm name
    - `description` string, nullable, required: Alarm description
    - `state` 'initial' | 'alarm' | 'ok', required: Current alarm state
    - `query` string, nullable, required: BadgerQL run on each check, as the text a create or update sent.
    - `stream_ids` string[], nullable, required: Associated stream identifiers
    - `evaluation_period` string, nullable, required: Window each evaluation covers, as a compact duration. The API rejects a spelled-out interval like `5 minutes`.
    - `lookback_lag` string, nullable, required: How far behind now the window ends, allowing for ingestion delay. Same compact duration format as `evaluation_period`.
    - `trigger_config` AlarmTriggerConfig, required: What turns the alarm on. Sent whole: on update, a `trigger_config` replaces the stored one rather than merging into it.
      - `type` 'alert_result_count', required: `alert_result_count` compares the number of results the query returns.
      - `config` AlarmTriggerCondition, required: The comparison against the query's result that fires the trigger
        - `operator` 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'neq', required: How the query's result is compared with `value`: greater than, greater than or equal, less than, less than or equal, equal, or not equal.
        - `value` number, double, required: Threshold to compare against. `alert_result_count` takes a whole number >= 0.
    - `error` string, nullable, required: Error message if the alarm is in an error state
    - `last_checked_at` string, date-time, nullable, required: When the alarm was last evaluated
    - `next_check_at` string, date-time, nullable, required: When the alarm will next be evaluated
    - `created_at` string, date-time, required: When the alarm was created
    - `updated_at` string, date-time, required: When the alarm was last updated
    - `links` WebLinks, required: Links into the Honeybadger web UI
      - `web` string, uri, required: The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have `links`. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on.
  - `meta` ResponseMeta
    - `request_id` string: Unique identifier for the request, for correlating with support

## Other responses

- `401`: The credential is missing, invalid, expired or revoked (`unauthorized`), or was sent in a way v3 doesn't accept (see the examples).
- `403`: The credential isn't allowed to do this. `error.code` says why. An account or project the credential doesn't cover is 404 `not_found`, not 403.
- `404`: Resource not found
- `422`: Validation error
- `429`: `stream_ids` was left out (or null) and the project's streams are still being set up, which a new project's are for a short time after it's created (`streams_provisioning`); or the rate limit is exceeded (`rate_limit_exceeded`). Nothing was created. Wait `Retry-After` seconds and retry.
- `503`: Alarms are temporarily unavailable. Retry later.

---

[API](https://skmtc.dev/honeybadger/apis/honeybadger-api.md) - [All operations](https://skmtc.dev/honeybadger/apis/honeybadger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/honeybadger/apis/honeybadger-api/revisions/cbcff53f2c8a?raw)