HOhoneycomb
Triggers

Create a Trigger

Changed on

Create a trigger on the provided dataset or environment.

post/1/triggers/{datasetSlug}

Request

  • Base URL
    https://api.honeycomb.io
  • URL
    https://api.honeycomb.io/1/triggers/{datasetSlug}
  • Auth
    API key in header X-Honeycomb-Team

Request body

OR

Example request

{
  "tags": [
    {
      "key": "team",
      "value": "blue"
    }
  ],
  "recipients": [
    {
      "details": {
        "variables": [
          {
            "name": "severity",
            "value": "warning"
          }
        ]
      }
    }
  ],
  "baseline_details": {
    "offset_minutes": 60,
    "type": "percentage"
  }
}

Response

Success - trigger created

idstring

The unique identifier (ID) for this Trigger.

dataset_slugstring

The slug of the dataset this trigger belongs to. For environment-wide triggers, this will be "all".

namestring

A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.

descriptionstring

A longer description, displayed on the Trigger's detail page.

frequencyinteger

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 for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900

alert_type'on_change' | 'on_true' | 'on_group_change'

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.)
  • on_group_change sends notifications when individual groups cross or resolve the threshold.
disabledboolean

If true, the trigger will not be evaluated and alerts will not be sent.

triggeredboolean

If true, the trigger has crossed its specified threshold without resolving.

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.

created_atstring date-time
updated_atstring date-time
auto_investigateboolean

When true, Honeycomb will automatically start an investigation when this Trigger fires.

queryobject

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.

query_idstring

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.

Example response

{
  "tags": [
    {
      "key": "team",
      "value": "blue"
    }
  ],
  "recipients": [
    {
      "details": {
        "variables": [
          {
            "name": "severity",
            "value": "warning"
          }
        ]
      }
    }
  ],
  "baseline_details": {
    "offset_minutes": 60,
    "type": "percentage"
  }
}

Changes

  • 276c5555582aRevision changes
    • breaking

      added subschema #2 to the ///////// request property allOf list

    • breaking

      added subschema #2 to the ///////// request property allOf list

    • breaking

      the ///////// request property type changed from object to no type

    • breaking

      the ///////// request property type changed from object to no type

    • breaking

      the ///////// response's property type changed from object to no type for status

    • breaking

      the ///////// response's property type changed from object to no type for status

    • warning

      removed the request property //////////

    • warning

      removed the request property //////////

    • warning

      removed the request property //////////

    • warning

      removed the request property //////////

    • warning

      removed the request property //////////

    • warning

      removed the request property //////////

    • warning

      removed the request property //////////

    • warning

      removed the request property //////////

    • warning

      removed the optional property ////////// from the response with the status

    • warning

      removed the optional property ////////// from the response with the status

    • warning

      removed the optional property ////////// from the response with the status

    • warning

      removed the optional property ////////// from the response with the status

    • warning

      removed the optional property ////////// from the response with the status

    • warning

      removed the optional property ////////// from the response with the status

    • warning

      removed the optional property ////////// from the response with the status

    • warning

      removed the optional property ////////// from the response with the status

    • warning

      added the new on_group_change enum value to the //////// response property for the response status

    • warning

      added the new on_group_change enum value to the //////// response property for the response status

    • info

      added the new on_group_change enum value to the request property ////////

    • info

      added the new on_group_change enum value to the request property ////////

    • info

      added subschema #2 to the ///////// response property allOf list for the response status

    • info

      added subschema #2 to the ///////// response property allOf list for the response status