---
title: "Update a Trigger"
method: PUT
path: "/1/triggers/{datasetSlug}/{triggerId}"
tags: ["Triggers"]
---

# Update a Trigger

`PUT /1/triggers/{datasetSlug}/{triggerId}`

Update a trigger by specifying the trigger ID and the same fields used when creating a new trigger.

## Request body

- TriggerResponse
  - `id` string — The unique identifier (ID) for this Trigger.
  - `dataset_slug` string — The slug of the dataset this trigger belongs to. For environment-wide triggers, this will be "__all__".
  - `name` string — A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
  - `description` string — A longer description, displayed on the Trigger's detail page.
  - `tags` Tag[] — A list of key-value pairs to help identify the Trigger.
    - `key` string, required — A key to identify the tag, lowercase letters only.
    - `value` string, required — A value for the tag, must begin with a lowercase letter, contain only alphanumeric characters (all letters lowercase) and special characters of `/` and `-` allowed.
  - `threshold` object — The threshold over which the trigger will fire, specified as both an operator and a value.
    - `op` '>' | '>=' | '<' | '<=', required
    - `value` number, required
    - `exceeded_limit` integer — The number of times the threshold must be met before an alert is sent.
  - `frequency` integer — The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. `duration <= frequency*4`). See [A Caveat on Time](https://docs.honeycomb.io/investigate/collaborate/share-query/define-query-json/#how-to-specify-an-absolute-time-range) for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
  - `alert_type` 'on_change' | 'on_true' — How often to fire an alert when a trigger threshold is crossed. - `on_change` sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition. - `on_true` keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)
  - `disabled` boolean — If true, the trigger will not be evaluated and alerts will not be sent.
  - `triggered` boolean — If true, the trigger has crossed its specified threshold without resolving.
  - `recipients` NotificationRecipient[] — A list of [Recipients](/api/recipients/) to notify when the Trigger fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
    - `id` string
    - `type` 'pagerduty' | 'email' | 'slack' | 'webhook' | 'msteams' | 'msteams_workflow' — One of the supported Recipient Types
    - `target` string — The target of the notification. For example, the specific Slack channel or email address. For Recipients of `type = "webhook"` or `type = "msteams_workflow"`, this will be the Name in the UI and `webhook_name` in the Recipients API. Deprecated: Use the Recipients API first, then pass the Recipient ID.
    - `details` NotificationRecipientDetails
      - `pagerduty_severity` 'critical' | 'error' | 'warning' | 'info' — When using a Recipient of `type = "pagerduty"`, the severity of the alert can be specified.
      - `variables` object[] — When using a Recipient of `type = "webhook"`, the alert-level variables can be specified.
        - `name` string, required
        - `value` string
  - `evaluation_schedule_type` 'frequency' | 'window' — The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
  - `evaluation_schedule` object — A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
    - `window` object, required — Window start/end times and days of the week are calculated in UTC. If the end time is the same as or earlier than the start time, the end time is treated as being in the following day.
      - `days_of_week` string[], required
      - `start_time` string, required — A UTC time in HH:mm format (13:00)
      - `end_time` string, required — A UTC time in HH:mm format (13:00)
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `baseline_details` union
    - object — Additional properties needed to configure this trigger with a dynamic baseline threshold.
      - `offset_minutes` 60 | 1440 | 10080 | 40320, required — For a given trigger run, how far back we should look to compare results. Currently only support comparison 1 hour, 24 hours, 7 days, or 28 days in the past.
      - `type` 'percentage' | 'value', required — How to compare the change in the two time periods. Currently supports the difference in values (b-a) or the percentage difference in values (b-a)/b.
    - object — Set to an empty object to clear the baseline threshold.
      - `offset_minutes` 60 | 1440 | 10080 | 40320, required — For a given trigger run, how far back we should look to compare results. Currently only support comparison 1 hour, 24 hours, 7 days, or 28 days in the past.
      - `type` 'percentage' | 'value', required — How to compare the change in the two time periods. Currently supports the difference in values (b-a) or the percentage difference in values (b-a)/b.
    - object — Additional properties needed to configure this trigger with a dynamic baseline threshold.
      - `offset_minutes` 60 | 1440 | 10080 | 40320, required — For a given trigger run, how far back we should look to compare results. Currently only support comparison 1 hour, 24 hours, 7 days, or 28 days in the past.
      - `type` 'percentage' | 'value', required — How to compare the change in the two time periods. Currently supports the difference in values (b-a) or the percentage difference in values (b-a)/b.
    - unknown
  - `auto_investigate` boolean — When true, Honeycomb will automatically start an investigation when this Trigger fires.
  - `query` object — An inline query specification that is a strict subset of the standard Query Specification. **Required Fields:** - `calculations`: At least one aggregate calculation (e.g., COUNT, AVG, SUM). Cannot use HEATMAP or CONCURRENCY. - `time_range`: Query duration in seconds. Must be between the trigger `frequency` and the lesser of (4 × `frequency`) or 86400 (24 hours). **Prohibited Fields:** - `orders`: Not supported. Trigger queries automatically order results based on the threshold operator. - `limit`: Not supported. All matching result groups are evaluated. - `start_time` and `end_time`: Not supported. Use `time_range` instead for relative time windows. - `usage_mode`: Not supported for triggers. **Calculation Restrictions:** - Without formulas: Maximum 1 non-having aggregate allowed. - With formulas: Maximum 1 formula allowed, with up to 100 aggregates. - Maximum 1 HAVING clause allowed, which must correspond to an existing calculation. - Named aggregates cannot be combined with global `filters`. **Metrics Dataset Specific:** - `granularity` field is supported and must be within calculated min/max bounds based on time range. - Nil aggregate values are skipped during trigger evaluation (no error, group is simply not evaluated). - Requires a non-legacy environment. **Standard Datasets:** - `granularity` field is not supported. Learn more about [Triggers](https://docs.honeycomb.io/notify/alert/triggers/).
  - `query_id` string — The ID of an existing saved Query that meets the trigger query requirements. The referenced query must satisfy the same restrictions as inline trigger queries: - Must have at least one aggregate calculation (not HEATMAP or CONCURRENCY) - Cannot have `orders`, `limit`, `start_time`, `end_time`, or `usage_mode` fields set - Must have appropriate `time_range` relative to trigger frequency - Must respect calculation restrictions (max 1 non-having aggregate without formulas, or max 1 formula with up to 100 aggregates) - Maximum 1 having clause allowed - Named aggregates cannot be combined with global filters - For metrics datasets: may include `granularity` field (within calculated bounds) - For standard datasets: must not include `granularity` field The API will validate the referenced query meets these criteria when creating or updating the trigger. See the inline `query` field documentation above for complete trigger query requirements and learn more about [Triggers](https://docs.honeycomb.io/notify/alert/triggers/).

## Response `200`

Success

- TriggerResponse
  - `id` string — The unique identifier (ID) for this Trigger.
  - `dataset_slug` string — The slug of the dataset this trigger belongs to. For environment-wide triggers, this will be "__all__".
  - `name` string — A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
  - `description` string — A longer description, displayed on the Trigger's detail page.
  - `tags` Tag[] — A list of key-value pairs to help identify the Trigger.
    - `key` string, required — A key to identify the tag, lowercase letters only.
    - `value` string, required — A value for the tag, must begin with a lowercase letter, contain only alphanumeric characters (all letters lowercase) and special characters of `/` and `-` allowed.
  - `threshold` object — The threshold over which the trigger will fire, specified as both an operator and a value.
    - `op` '>' | '>=' | '<' | '<=', required
    - `value` number, required
    - `exceeded_limit` integer — The number of times the threshold must be met before an alert is sent.
  - `frequency` integer — The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. `duration <= frequency*4`). See [A Caveat on Time](https://docs.honeycomb.io/investigate/collaborate/share-query/define-query-json/#how-to-specify-an-absolute-time-range) for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
  - `alert_type` 'on_change' | 'on_true' — How often to fire an alert when a trigger threshold is crossed. - `on_change` sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition. - `on_true` keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)
  - `disabled` boolean — If true, the trigger will not be evaluated and alerts will not be sent.
  - `triggered` boolean — If true, the trigger has crossed its specified threshold without resolving.
  - `recipients` NotificationRecipient[] — A list of [Recipients](/api/recipients/) to notify when the Trigger fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
    - `id` string
    - `type` 'pagerduty' | 'email' | 'slack' | 'webhook' | 'msteams' | 'msteams_workflow' — One of the supported Recipient Types
    - `target` string — The target of the notification. For example, the specific Slack channel or email address. For Recipients of `type = "webhook"` or `type = "msteams_workflow"`, this will be the Name in the UI and `webhook_name` in the Recipients API. Deprecated: Use the Recipients API first, then pass the Recipient ID.
    - `details` NotificationRecipientDetails
      - `pagerduty_severity` 'critical' | 'error' | 'warning' | 'info' — When using a Recipient of `type = "pagerduty"`, the severity of the alert can be specified.
      - `variables` object[] — When using a Recipient of `type = "webhook"`, the alert-level variables can be specified.
        - `name` string, required
        - `value` string
  - `evaluation_schedule_type` 'frequency' | 'window' — The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
  - `evaluation_schedule` object — A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
    - `window` object, required — Window start/end times and days of the week are calculated in UTC. If the end time is the same as or earlier than the start time, the end time is treated as being in the following day.
      - `days_of_week` string[], required
      - `start_time` string, required — A UTC time in HH:mm format (13:00)
      - `end_time` string, required — A UTC time in HH:mm format (13:00)
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `baseline_details` union
    - object — Additional properties needed to configure this trigger with a dynamic baseline threshold.
      - `offset_minutes` 60 | 1440 | 10080 | 40320, required — For a given trigger run, how far back we should look to compare results. Currently only support comparison 1 hour, 24 hours, 7 days, or 28 days in the past.
      - `type` 'percentage' | 'value', required — How to compare the change in the two time periods. Currently supports the difference in values (b-a) or the percentage difference in values (b-a)/b.
    - object — Set to an empty object to clear the baseline threshold.
      - `offset_minutes` 60 | 1440 | 10080 | 40320, required — For a given trigger run, how far back we should look to compare results. Currently only support comparison 1 hour, 24 hours, 7 days, or 28 days in the past.
      - `type` 'percentage' | 'value', required — How to compare the change in the two time periods. Currently supports the difference in values (b-a) or the percentage difference in values (b-a)/b.
    - object — Additional properties needed to configure this trigger with a dynamic baseline threshold.
      - `offset_minutes` 60 | 1440 | 10080 | 40320, required — For a given trigger run, how far back we should look to compare results. Currently only support comparison 1 hour, 24 hours, 7 days, or 28 days in the past.
      - `type` 'percentage' | 'value', required — How to compare the change in the two time periods. Currently supports the difference in values (b-a) or the percentage difference in values (b-a)/b.
    - unknown
  - `auto_investigate` boolean — When true, Honeycomb will automatically start an investigation when this Trigger fires.
  - `query` object — An inline query specification that is a strict subset of the standard Query Specification. **Required Fields:** - `calculations`: At least one aggregate calculation (e.g., COUNT, AVG, SUM). Cannot use HEATMAP or CONCURRENCY. - `time_range`: Query duration in seconds. Must be between the trigger `frequency` and the lesser of (4 × `frequency`) or 86400 (24 hours). **Prohibited Fields:** - `orders`: Not supported. Trigger queries automatically order results based on the threshold operator. - `limit`: Not supported. All matching result groups are evaluated. - `start_time` and `end_time`: Not supported. Use `time_range` instead for relative time windows. - `usage_mode`: Not supported for triggers. **Calculation Restrictions:** - Without formulas: Maximum 1 non-having aggregate allowed. - With formulas: Maximum 1 formula allowed, with up to 100 aggregates. - Maximum 1 HAVING clause allowed, which must correspond to an existing calculation. - Named aggregates cannot be combined with global `filters`. **Metrics Dataset Specific:** - `granularity` field is supported and must be within calculated min/max bounds based on time range. - Nil aggregate values are skipped during trigger evaluation (no error, group is simply not evaluated). - Requires a non-legacy environment. **Standard Datasets:** - `granularity` field is not supported. Learn more about [Triggers](https://docs.honeycomb.io/notify/alert/triggers/).
  - `query_id` string — The ID of an existing saved Query that meets the trigger query requirements. The referenced query must satisfy the same restrictions as inline trigger queries: - Must have at least one aggregate calculation (not HEATMAP or CONCURRENCY) - Cannot have `orders`, `limit`, `start_time`, `end_time`, or `usage_mode` fields set - Must have appropriate `time_range` relative to trigger frequency - Must respect calculation restrictions (max 1 non-having aggregate without formulas, or max 1 formula with up to 100 aggregates) - Maximum 1 having clause allowed - Named aggregates cannot be combined with global filters - For metrics datasets: may include `granularity` field (within calculated bounds) - For standard datasets: must not include `granularity` field The API will validate the referenced query meets these criteria when creating or updating the trigger. See the inline `query` field documentation above for complete trigger query requirements and learn more about [Triggers](https://docs.honeycomb.io/notify/alert/triggers/).

## Other responses

- `400` — Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Invalid request
- `429` — Rate Limit Exceeded

---

[API](https://skmtc.net/honeycomb/apis/honeycomb-api.md) · [All operations](https://skmtc.net/honeycomb/apis/honeycomb-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/honeycomb/honeycomb-api/versions/117619fac2a5/schema)