---
title: Update an alarm
description: Updates an alarm's settings.
url: https://docs.honeybadger.io/api/v3/alarms/update-alarm/
---

API v3 is in preview

Endpoints and response shapes [can change before general availability](https://docs.honeybadger.io/api/v3/#preview). API v2 is unchanged.

PATCH `https://app.honeybadger.io/v3/projects/{project_id}/alarms/{alarm_id}`

[Required scope](https://docs.honeybadger.io/api/v3/authentication/#scopes) `alarms:write`

Updates an alarm’s settings.

Example request

```sh
curl -X PATCH "https://app.honeybadger.io/v3/projects/$PROJECT_ID/alarms/$ALARM_ID" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Slow checkouts"
}'
```

## Parameters

### Path parameters

| Field | Type | Description |
| - | - | - |
| `project_id` required | string | Project ID. |
| `alarm_id` required | string | Alarm ID. |

## Request body

| Field | Type | Description |
| - | - | - |
| `name` | string | Alarm name. |
| `description` | string \| null | What the alarm watches for, shown with it in Honeybadger. Null clears it. |
| `query` | string | BadgerQL query evaluated on each check. |
| `stream_ids` | array \| null | Stream identifiers to query. A set; can't be empty. Order is ignored and duplicates are dropped. Null resets it to every current stream in the project. |
| `evaluation_period` | string | Window each evaluation covers, as a compact duration. At least 1m and less than a week (`w` units are refused). |
| `lookback_lag` | string | How far behind now the window ends. |
| `trigger_config` | object | What turns the alarm on. Sent whole: on update, a `trigger_config` replaces the stored one rather than merging into it. |
| `trigger_config.type` required | string | `alert_result_count` compares the number of results the query returns. Allowed values: `alert_result_count`. |
| `trigger_config.config` required | object | The comparison against the query's result that fires the trigger. |
| `trigger_config.config.operator` required | string | 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. Allowed values: `gt`, `gte`, `lt`, `lte`, `eq`, `neq`. |
| `trigger_config.config.value` required | number | Threshold to compare against. `alert_result_count` takes a whole number >= 0. |

## Responses

### 200 Success

Example payload

```json
{
  "data": {
    "id": "Qx7LmP2vRt9K",
    "project_id": "Xk9mZp",
    "name": "High Error Rate",
    "description": "Fires when checkout errors spike",
    "state": "initial",
    "query": "filter event_type::str == \"notice\" | stats count() as count",
    "stream_ids": [
      "string"
    ],
    "evaluation_period": "10m",
    "lookback_lag": "1m",
    "trigger_config": {
      "type": "alert_result_count",
      "config": {
        "operator": "gt",
        "value": 10
      }
    },
    "error": null,
    "last_checked_at": "2026-01-01T00:00:00Z",
    "next_check_at": "2026-01-01T00:00:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "links": {
      "web": "https://app.honeybadger.io/projects/Xk9mZp"
    }
  },
  "meta": {
    "request_id": "6f1c2b0e-8d4a-4f6e-9b2a-3c5d7e9f1a2b"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `data` required | object | 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. |
| `data.id` required | string | |
| `data.project_id` required | string | ID of the project this alarm belongs to. |
| `data.name` required | string | Alarm name. |
| `data.description` required | string \| null | Alarm description. |
| `data.state` required | string | Current alarm state. Allowed values: `initial`, `alarm`, `ok`. |
| `data.query` required | string \| null | BadgerQL run on each check, as the text a create or update sent. |
| `data.stream_ids` required | array \| null | Associated stream identifiers. |
| `data.evaluation_period` required | string \| null | Window each evaluation covers, as a compact duration. The API rejects a spelled-out interval like `5 minutes`. |
| `data.lookback_lag` required | string \| null | How far behind now the window ends, allowing for ingestion delay. Same compact duration format as `evaluation_period`. |
| `data.trigger_config` required | object \| null | What turns the alarm on; null if the stored alarm has none. Updates replace the whole object. |
| `data.trigger_config.type` required | string | `alert_result_count` compares the number of results the query returns. Allowed values: `alert_result_count`. |
| `data.trigger_config.config` required | object | The comparison against the query's result that fires the trigger. |
| `data.trigger_config.config.operator` required | string | 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. Allowed values: `gt`, `gte`, `lt`, `lte`, `eq`, `neq`. |
| `data.trigger_config.config.value` required | number | Threshold to compare against. `alert_result_count` takes a whole number >= 0. |
| `data.error` required | string \| null | Error message if the alarm is in an error state. |
| `data.last_checked_at` required | date-time \| null | When the alarm was last evaluated. |
| `data.next_check_at` required | date-time \| null | When the alarm will next be evaluated. |
| `data.created_at` required | date-time | When the alarm was created. |
| `data.updated_at` required | date-time | When the alarm was last updated. |
| `data.links` required | object | Links into the Honeybadger web UI. |
| `data.links.web` required | uri | 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` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

## Errors

### 401 Unauthorized

The credential is missing, invalid, expired or revoked (`unauthorized`), or was sent in a way v3 doesn’t accept (see the examples).

Example payload: unauthorized (Missing, malformed, expired or revoked credential)

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: unsupported\_auth\_scheme (Sent as HTTP basic, which v3 does not accept)

```json
{
  "error": {
    "code": "unsupported_auth_scheme",
    "message": "Send the credential as `Authorization: Bearer <token>`; v3 does not accept HTTP basic"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: credential\_in\_query (Sent as the \`auth\_token\` query parameter)

```json
{
  "error": {
    "code": "credential_in_query",
    "message": "Credentials must be sent in the Authorization header"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 403 Forbidden

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.

Example payload: access\_denied (The credential isn't allowed to do this to this record)

```json
{
  "error": {
    "code": "access_denied",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: insufficient\_scope (The credential lacks the permission this endpoint requires)

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {
      "required_scope": "faults:write",
      "token_scopes": [
        "faults:read",
        "insights:read"
      ]
    }
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: requires\_user\_token (The endpoint records who acted, and an account token has nobody)

```json
{
  "error": {
    "code": "requires_user_token",
    "message": "This endpoint records the person who acted, so it requires a user credential rather than an account token"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: project\_restricted (A project-restricted credential cannot create a project)

```json
{
  "error": {
    "code": "project_restricted",
    "message": "Project-restricted tokens cannot create projects"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 404 Not Found

Resource not found

Example payload

```json
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 422 Unprocessable Content

Validation error

Example payload

```json
{
  "error": {
    "code": "validation_error",
    "message": "Name can't be blank",
    "details": [
      {
        "field": "name",
        "message": "can't be blank"
      }
    ]
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 503 Service Unavailable

Alarms are temporarily unavailable. Retry later.

Example payload

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "Alarm service unavailable, please try again later"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

---

## 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/)