Create an alarm

API v3 is in preview

Endpoints and response shapes can change before general availability. API v2 is unchanged.

POST https://app.honeybadger.io/v3/projects/{project_id}/alarms

Required scope alarms:write

Creates a new alarm for the project.

Example request

curl -X POST "https://app.honeybadger.io/v3/projects/$PROJECT_ID/alarms" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Error spike",
  "query": "filter event_type::str == \"notice\" | stats count() as count",
  "evaluation_period": "10m",
  "lookback_lag": "1m",
  "trigger_config": {
    "type": "alert_result_count",
    "config": {
      "operator": "gt",
      "value": 10
    }
  }
}'

Parameters

1

Path parameters

Field	Type	Description
project_id required	string	Project ID.

Request body

Field	Type	Description
name required	string	Alarm name.
description	string | null	What the alarm watches for, shown with it in Honeybadger. Null clears it.
query required	string	BadgerQL evaluated on each check.
stream_ids	array | null	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 required	string	Window each evaluation covers. At least 1m and less than a week (w units are refused).
lookback_lag required	string	How far behind now the window ends, allowing for ingestion delay.
trigger_config required	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

1

201 Alarm created

Example payload

{
  "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 schema24

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

6

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)

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

Example payload: unsupported_auth_scheme (Sent as HTTP basic, which v3 does not accept)

{
  "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)

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

Response schema6

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)

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

Example payload: insufficient_scope (The credential lacks the permission this endpoint requires)

{
  "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)

{
  "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)

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

Response schema6

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

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

Response schema6

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

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

Response schema6

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.

429 Too Many Requests

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.

Example payload

{
  "error": {
    "code": "streams_provisioning",
    "message": "The project's streams are still being set up; retry shortly"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

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

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

Response schema6

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.