logo

Triggers

Triggers let you receive notifications when your data in Honeycomb crosses the thresholds that you configure. The graph on which to alert is as flexible as a Honeycomb query, which helps reduce false positives due to known errors.Triggers fire

This API allows you to list, create, update, and delete Triggers.

Authorization

The API key must have the Manage Triggers permission. Learn more about API keys here.

List All Triggers

List all triggers on the provided dataset.

Securityapi_key
Request
path Parameters
datasetSlug
required
string

The dataset slug.

Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

default

Error

get/1/triggers/{datasetSlug}
Request samples 
Response samples 
application/json
[
  • {
    }
]
Create a Trigger
Create a trigger on the provided dataset.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug.


 
Request Body schema: application/json
required
One of:
name
string  [ 1 .. 120 ] characters 
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.


 
description
string  <= 1023 characters 
A longer description, displayed on the Trigger's detail page.


 
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
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.)
    • 



 Enum: "on_change" "on_true"  
disabled
boolean
 Default:  false
If true, the trigger will not be evaluated and alerts will not be sent.


 
Array of objects (NotificationRecipient) 
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
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.


 Enum: "frequency" "window"  
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.


 
query
object
A query ID or an inline query that is a strict subset of a Query Specification.


 
Responses 
201
Success - trigger created


400
The provided request body was invalid. Most APIs will return a DetailedError for this condition, explaining what went wrong, but some older APIs only return a GenericError.


401
Unauthorized


404
Not Found


413
The provided request body was over the maximum allowed size.


422
Invalid request


post/1/triggers/{datasetSlug}
Request samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "threshold": {
    },
  • "frequency": 0,
  • "alert_type": "on_change",
  • "disabled": false,
  • "recipients": [
    ],
  • "evaluation_schedule_type": "frequency",
  • "evaluation_schedule": {
    },
  • "query": { }
}
Response samples 
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "threshold": {
    },
  • "frequency": 0,
  • "alert_type": "on_change",
  • "disabled": false,
  • "triggered": true,
  • "recipients": [
    ],
  • "evaluation_schedule_type": "frequency",
  • "evaluation_schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "query": { },
  • "query_id": "string"
}
Get a Trigger
Fetch details for a single Trigger by Trigger ID.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug.


 
triggerId
required
string
The unique identifier (ID) of a Trigger.


 
Responses 
200
Success


401
Unauthorized


404
Not Found


get/1/triggers/{datasetSlug}/{triggerId}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "threshold": {
    },
  • "frequency": 0,
  • "alert_type": "on_change",
  • "disabled": false,
  • "triggered": true,
  • "recipients": [
    ],
  • "evaluation_schedule_type": "frequency",
  • "evaluation_schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "query": { },
  • "query_id": "string"
}
Update a Trigger
Update a trigger by specifying the trigger ID and the same fields used when creating a new trigger.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug.


 
triggerId
required
string
The unique identifier (ID) of a Trigger.


 
Request Body schema: application/json
required
name
string  [ 1 .. 120 ] characters 
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.


 
description
string  <= 1023 characters 
A longer description, displayed on the Trigger's detail page.


 
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
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.)
    • 



 Enum: "on_change" "on_true"  
disabled
boolean
 Default:  false
If true, the trigger will not be evaluated and alerts will not be sent.


 
Array of objects
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
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.


 Enum: "frequency" "window"  
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.


 
query
object
A query ID or an inline query that is a strict subset of a Query Specification.


 
query_id
string
The ID of a Query that meets the criteria for being used as a Trigger, per above.


 
Responses 
200
Success


400
Error


401
Unauthorized


404
Not Found


422
Invalid request


put/1/triggers/{datasetSlug}/{triggerId}
Request samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "threshold": {
    },
  • "frequency": 0,
  • "alert_type": "on_change",
  • "disabled": false,
  • "recipients": [
    ],
  • "evaluation_schedule_type": "frequency",
  • "evaluation_schedule": {
    },
  • "query": { },
  • "query_id": "string"
}
Response samples 
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "threshold": {
    },
  • "frequency": 0,
  • "alert_type": "on_change",
  • "disabled": false,
  • "triggered": true,
  • "recipients": [
    ],
  • "evaluation_schedule_type": "frequency",
  • "evaluation_schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "query": { },
  • "query_id": "string"
}
Delete a Trigger
Delete a trigger by specifying the trigger ID. The body of the DELETE request should be empty.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug.


 
triggerId
required
string
The unique identifier (ID) of a Trigger.


 
Responses 
204
Success - no content


401
Unauthorized


404
Not Found


delete/1/triggers/{datasetSlug}/{triggerId}
Request samples 
Response samples 
application/json
{
  • "error": "unknown API key - check your credentials"
}
Get Triggers Associated with a Recipient
List all triggers that will alert a given Recipient. Important: This request will return all Triggers associated with the specific Recipient across your entire Honeycomb team rather than being scoped to a dataset or environment.


Securityapi_key 
Request 
path Parameters
recipientId
required
string
Unique identifier (ID) of a Recipient.


 
Responses 
200
Success


401
Unauthorized


404
Not Found


default
Error


get/1/recipients/{recipientId}/triggers
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "threshold": {
    },
  • "frequency": 0,
  • "alert_type": "on_change",
  • "disabled": false,
  • "triggered": true,
  • "recipients": [
    ],
  • "evaluation_schedule_type": "frequency",
  • "evaluation_schedule": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "query": { },
  • "query_id": "string"
}
➔ Next to Errors