Skip to main content
GET
/
1
/
triggers
/
{datasetSlug}
List All Triggers
curl --request GET \
  --url https://api.honeycomb.io/1/triggers/{datasetSlug}
[
  {
    "id": "<string>",
    "dataset_slug": "<string>",
    "name": "<string>",
    "description": "<string>",
    "tags": [
      {
        "key": "team",
        "value": "blue"
      }
    ],
    "threshold": {
      "op": ">",
      "value": 123,
      "exceeded_limit": 1
    },
    "frequency": 123,
    "alert_type": "on_change",
    "disabled": false,
    "triggered": true,
    "recipients": [
      {
        "id": "<string>",
        "type": "pagerduty",
        "target": "<string>",
        "details": {
          "pagerduty_severity": "critical",
          "variables": [
            {
              "name": "severity",
              "value": "warning"
            }
          ]
        }
      }
    ],
    "evaluation_schedule_type": "frequency",
    "evaluation_schedule": {
      "window": {
        "days_of_week": [
          "sunday"
        ],
        "start_time": 840,
        "end_time": 1260
      }
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "baseline_details": {
      "offset_minutes": 60,
      "type": "percentage"
    },
    "query": {},
    "query_id": "<string>"
  }
]

Path Parameters

​
datasetSlug
string
required

The dataset slug or use __all__ for endpoints that support environment-wide operations.

Response

OK

​
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.

Required string length: 1 - 120
​
description
string

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

Maximum string length: 1023
​
tags
object[]

A list of key-value pairs to help identify the Trigger.

Maximum array length: 10
Example:
[{ "key": "team", "value": "blue" }]
​
threshold
object

The threshold over which the trigger will fire, specified as both an operator and a value.

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

​
alert_type
enum<string>
default:on_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.)
Available options:
on_change,
on_true
​
disabled
boolean
default:false

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
object[]

A list of 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.

​
evaluation_schedule_type
enum<string>

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.

Available options:
frequency,
window
​
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.

​
created_at
string<date-time>
​
updated_at
string<date-time>
​
baseline_details
object

Additional properties needed to configure this trigger with a dynamic baseline threshold.

Example:
{
  "offset_minutes": 60,
  "type": "percentage"
}
​
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.

​
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.