> ## Documentation Index > Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml api/openapi-public.yaml get /1/recipients/{recipientId}/triggers openapi: 3.1.0 info: title: Honeycomb API version: 1.0.0 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html contact: email: support@honeycomb.io description: > The API allows programmatic management of many resources within Honeycomb. Please report any discrepancies with actual API behavior in Pollinators Slack or to Honeycomb Support. servers: - url: https://api.honeycomb.io - url: https://api.eu1.honeycomb.io security: [] tags: - name: Auth description: > API Keys have various scopes permissions and belong to a specific Team or Environment. Any valid Honeycomb ingest or configuration API Key will work with this endpoint. Learn more about [API keys](https://docs.honeycomb.io/get-started/best-practices/api-keys). These endpoints can be used to validate authentication for a key, to determine what authorizations have been granted to a key, and to determine the Team and Environment that a key belongs to. - name: Boards description: > Boards are a place to pin and save useful queries/graphs, SLO panels, text panels, and views you want to retain for later reuse and reference. Boards can contain multiple panel types: - **Query panels**: Display saved queries/graphs - **SLO panels**: Monitor Service Level Objectives - **Text panels**: Add markdown-formatted text and documentation - **Views**: Filtered perspectives of board data (limited to 50 views per board) Boards also support preset filters (limited to 5 per board) to apply consistent filtering across the board. This API allows you to list, create, update, and delete boards, as well as manage board views. ## Authorization The API key must have the **Manage Public Boards** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Burn Alerts description: > This feature is available as part of the [Honeycomb Pro and Enterprise plans](https://www.honeycomb.io/pricing/). Burn Alerts notify you when issues impact your SLO budget. Learn more about [Burn Alerts here](https://docs.honeycomb.io/notify/alert/slos/monitor/). This API allows you to list, create, update, and delete burn alerts. ## Authorization The API key must have the **Manage SLOs** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Calculated Fields description: > Calculated Fields (also called Derived Columns) allow you to run queries based on the value of an expression that is calculated from the fields in an event. This API allows you to list, create, update, and delete Calculated Fields in a dataset or across a whole environment, paralleling the behavior of the Schema tab within a Dataset's or Environment's Settings UI. ## Authorization The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Columns description: > Columns are fields in the events you send to Honeycomb. This API allows you to list, create, update, and delete columns in a dataset. ## Authorization The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Datasets description: > A Dataset represents a collection of related events that come from the same source, or are related to the same source. This API allows you to list, create, and update datasets. ## Authorization The API key must have the **Create Datasets** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Dataset Definitions description: > Dataset definitions describe the fields with special meaning in the Dataset. Refer to the [Dataset Definitions](https://docs.honeycomb.io/configure/datasets/definitions/) documentation for more information. **Honeycomb automatically creates these Dataset definition fields when the Dataset is created.** Manual creation of Dataset definitions is **not** needed. ## Authorization The API key must have the **Create Datasets** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Events description: > The Events API endpoints are the lowest-level way to send Events to Honeycomb. **This should be your last resort!** If unsure where to start when instrumenting an application, read about how to [Send Data to Honeycomb](https://docs.honeycomb.io/send-data/). If you are building a tracing or metrics library, we recommend using [OpenTelemetry](https://docs.honeycomb.io/send-data/opentelemetry/). ## Authorization It is recommended that an Ingest API key is used for sending events. A Configuration API key will work, and must have the **Send Events** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Environments description: > This API allows you to list, create, and update, and delete Environments. ## Authorization This API requires a Management Key passed via the HTTP Authorization header. Join the key ID and secret with a colon, like this: `Authorization: Bearer :`. - name: Key Management description: > This API allows you to list, create, update, and delete API Keys for a Team. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). ## Authorization This API requires a Management Key passed via the HTTP Authorization header. Join the key ID and secret with a colon, like this: `Authorization: Bearer :`. - name: Kinesis Events description: > The Kinesis Events API endpoints allow Honeycomb to process streaming events from Amazon Kinesis. Refer to the [Honeycomb AWS integrations](https://docs.honeycomb.io/integrations/aws/how-aws-integrations-work/) documentation for more information. ## Authorization It is recommended that an Ingest API key is used for sending events. A Configuration API key will work, and must have the **Send Events** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Markers description: > Markers indicate points in time on graphs where interesting things happen, such as deploys or outages. This API allows you to list, create, update, and delete Markers. ## Authorization The API key must have the **Manage Markers** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Marker Settings description: > Marker Settings apply to groups of similar Markers. For example, "deploys" markers appear with the same color on a graph. This API allows you to list, create, update, and delete Marker Settings. ## Authorization The API key must have the **Manage Markers** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Queries description: > Queries in Honeycomb are specifications for queries, and are used to identify queries in other parts of the API - in particular: boards, triggers, and query annotations. This API allows you to create and get query objects. ## Authorization The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Query Annotations description: > Query Annotations in Honeycomb allow you to associate names and descriptions to queries to add additional information in collaboration features. This API allows you to list, create, update, and delete Query Annotations. ## Authorization The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Query Data description: > This feature is available as part of the [Honeycomb Enterprise plan](https://www.honeycomb.io/pricing/). Query Results are the aggregated data from a Query, similar to what is displayed in graphs or heatmaps within the Honeycomb UI. Receiving results from a Query is a three-step process: Create the Query (or Query Spec), which validates that the query parameters are valid. Creating a query does not actually run the query to get results. Run the query asynchronously by creating a Query Result referencing the Query’s ID. This returns a Query Result ID. Poll the query result endpoint (with the Query Result ID) until the data is ready. Note that many Query Results can be created from a single Query. This is particularly useful when using a relative time_range parameter in the Query. For example, a Query with `time_range: 7200` and no explicit `start_time` or `end_time` can be re-run over and over, with each resulting Query Result containing the most recent 2 hours of data. This is conceptually similar to clicking Run Query in the Honeycomb UI without changing any query parameters. **IMPORTANT API RESTRICTIONS:** To ensure the stability of Honeycomb systems, we have enabled the following API restrictions. These restrictions may change over time. * Query Results can only be created for events with timestamps within the past 7 days. * When creating a Query Result, the time ranges from the Query are truncated according to the following rules. For queries with a time range of: * less than or equal to 6 hours, results are truncated to the nearest 1 minute. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:28:00Z. * greater than 6 hours and less than or equal to 2 days, results are truncated to the nearest 5 minutes. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:25:00Z. * greater than 2 days and less than or equal to 7 days, results are truncated to the nearest 30 minutes. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:00:00Z. * Creating a Query Result is rate limited to 10 requests per minute. Status code 429 will be returned when rate limited. * Query Results cannot take longer than 10 seconds to run. * Creating a Query Result that contains Relational Fields is rate limited to 1 request per minute. Status code 429 will be returned when rate limited. * Query Results with Relational Fields may be more likely to take longer to run. * Regardless of whether the `compare_time_offset_seconds` field is populated on a query, query run responses will not include comparison results. ## Authorization The API key must have the **Manage Queries and Columns** and **Run Queries** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Recipients description: > Honeycomb Recipients allow you to define and manage the Recipients that will get notified by a Trigger or Burn Alert. The types of Recipients supported are: PagerDuty, Email, Webhook, Microsoft Teams, and Slack. ## Authorization The API key must have the **Manage Recipients** permission. Recipients are team-wide and NOT environment-specific. API Keys with the **Manage Recipients** permission can modify recipients used by ALL environments for a given team. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Reporting description: > The Reporting API provides access to historical performance data. ## Authorization The API key must have the **Manage SLOs** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Service Maps description: > The Service Maps API endpoints allow you to visualize the relationships between your services in Honeycomb. This API allows you to create and retrieve service Dependency Requests, which are used to generate maps of dependencies between services. ## Authorization The API key must have the **Read Service Maps** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: SLOs description: > This feature is available as part of the [Honeycomb Pro and Enterprise plans](https://www.honeycomb.io/pricing). Honeycomb SLOs allow you to define and monitor Service Level Objectives (SLOs) for your organization. This API allows you to list, create, update, and delete SLO objects. You can also access historical reporting for your SLOs to analyze long-term performance trends. For more information, see [Get SLO History](https://api-docs.honeycomb.io/api/reporting/getslohistory) ## Authorization The API key must have the **Manage SLOs** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - name: Triggers description: > 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 support both standard event-based datasets and metrics datasets. Metrics triggers have additional capabilities such as granularity control. Learn more in the [Triggers documentation](https://docs.honeycomb.io/notify/alert/triggers/). 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](https://docs.honeycomb.io/configure/environments/manage-api-keys/). externalDocs: url: https://docs.honeycomb.io paths: /1/recipients/{recipientId}/triggers: parameters: - $ref: '#/components/parameters/recipientId' get: tags: - Triggers summary: Get Triggers Associated with a Recipient description: > 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. operationId: listTriggersWithRecipient responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: type: array items: $ref: '#/components/schemas/TriggerResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' security: - configuration_key: [] components: parameters: recipientId: name: recipientId description: Unique identifier (ID) of a Recipient. in: path required: true schema: type: string headers: RateLimit: description: | The (draft07) recommended header from the IETF on rate limiting. The value of the header is formatted "limit=X, remaining=Y, reset=Z". Where: - X is the maximum number of requests allowed in the window - Y is the number of requests remaining in the window - Z is the number of seconds until the limit resets schema: type: string example: limit=100, remaining=50, reset=60 RateLimitPolicy: description: | The (draft07) recommended header from the IETF on rate limiting. The value of the header is formatted "X;w=Y". Where: - X is the maximum number of requests allowed in a window - Y is the size of the window in seconds schema: type: string example: 100;w=60 RetryAfter: description: | The RFC7231 header used to indicate when a client should retry requests. schema: type: string example: Fri, 22 Mar 2024 18:37:53 GMT schemas: TriggerResponse: allOf: - $ref: '#/components/schemas/TriggerWithInlineQuery' - $ref: '#/components/schemas/TriggerWithQueryReference' TriggerWithInlineQuery: allOf: - $ref: '#/components/schemas/BaseTrigger' - type: object properties: query: type: object description: > 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/). properties: {} TriggerWithQueryReference: allOf: - $ref: '#/components/schemas/BaseTrigger' - type: object properties: query_id: type: string description: > 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/). Error: x-tags: - Errors type: object description: A legacy error, containing only a textual description. properties: error: type: string readOnly: true JSONAPIError: x-tags: - Errors type: object description: A JSONAPI-formatted error message. properties: errors: type: array items: type: object readOnly: true required: - id - code properties: id: type: string readOnly: false status: type: string code: type: string readOnly: true title: type: string readOnly: true detail: type: string readOnly: true source: type: object readOnly: true properties: pointer: type: string readOnly: true header: type: string readOnly: true parameter: type: string readOnly: true DetailedError: x-tags: - Errors description: An RFC7807 'Problem Detail' formatted error message. type: object required: - error - status - type - title properties: error: type: string readOnly: true default: something went wrong! status: type: number readOnly: true description: The HTTP status code of the error. type: type: string readOnly: true description: Type is a URI used to uniquely identify the type of error. title: type: string readOnly: true description: >- Title is a human-readable summary that explains the `type` of the problem. detail: type: string readOnly: true description: The general, human-readable error message. instance: type: string readOnly: true description: The unique identifier (ID) for this specific error. BaseTrigger: type: object properties: id: type: string readOnly: true description: The unique identifier (ID) for this Trigger. dataset_slug: type: string readOnly: true description: >- The slug of the dataset this trigger belongs to. For environment-wide triggers, this will be "__all__". name: type: string description: > A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires. minLength: 1 maxLength: 120 description: type: string description: | A longer description, displayed on the Trigger's detail page. maxLength: 1023 tags: type: array description: A list of key-value pairs to help identify the Trigger. maxItems: 10 items: $ref: '#/components/schemas/Tag' example: - key: team value: blue threshold: type: object required: - op - value description: > The threshold over which the trigger will fire, specified as both an operator and a value. properties: op: type: string enum: - '>' - '>=' - < - <= value: type: number exceeded_limit: type: integer description: > The number of times the threshold must be met before an alert is sent. default: 1 minimum: 1 maximum: 5 frequency: type: integer description: > 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: type: string description: > 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 default: on_change disabled: type: boolean default: false description: > If true, the trigger will not be evaluated and alerts will not be sent. triggered: type: boolean readOnly: true description: > If true, the trigger has crossed its specified threshold without resolving. recipients: type: array description: > 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. items: $ref: '#/components/schemas/NotificationRecipient' evaluation_schedule_type: type: string description: > 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 evaluation_schedule: type: object description: > 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. required: - window properties: window: type: object description: > 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. required: - days_of_week - start_time - end_time properties: days_of_week: type: array minItems: 1 maxItems: 7 items: type: string enum: - sunday - monday - tuesday - wednesday - thursday - friday - saturday start_time: type: string description: A UTC time in HH:mm format (13:00) example: 840 pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$ end_time: type: string description: A UTC time in HH:mm format (13:00) example: 1260 pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$ created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true baseline_details: type: object oneOf: - required: - offset_minutes - type description: > Additional properties needed to configure this trigger with a dynamic baseline threshold. properties: offset_minutes: type: integer enum: - 60 - 1440 - 10080 - 40320 description: > 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: type: string enum: - percentage - value description: > 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. example: offset_minutes: 60 type: percentage - description: Set to an empty object to clear the baseline threshold. additionalProperties: false example: {} Tag: type: object required: - key - value properties: key: type: string description: A key to identify the tag, lowercase letters only. maxLength: 32 value: type: string description: >- A value for the tag, must begin with a lowercase letter, contain only alphanumeric characters (all letters lowercase) and special characters of `/` and `-` allowed. maxLength: 128 NotificationRecipient: type: object properties: id: type: string type: deprecated: true description: > One of the allowed Recipient types. Deprecated: Use the Recipients API first, then pass the Recipient ID. allOf: - $ref: '#/components/schemas/RecipientType' target: type: string deprecated: true description: > 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: $ref: '#/components/schemas/NotificationRecipientDetails' RecipientType: type: string description: One of the supported Recipient Types enum: - pagerduty - email - slack - webhook - msteams - msteams_workflow NotificationRecipientDetails: type: object properties: pagerduty_severity: description: > When using a Recipient of `type = "pagerduty"`, the severity of the alert can be specified. type: string default: critical enum: - critical - error - warning - info variables: description: > When using a Recipient of `type = "webhook"`, the alert-level variables can be specified. type: array items: type: object required: - name properties: name: type: string pattern: ^[a-z](?:[a-zA-Z0-9]+$)?$ maxLength: 64 example: severity value: type: string maxLength: 256 example: warning responses: Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unknown API key - check your credentials application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' NotFound: description: Not Found headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: dataset not found application/problem+json: schema: $ref: '#/components/schemas/DetailedError' example: status: 404 type: https://api.honeycomb.io/problems/not-found title: The requested resource cannot be found. error: Dataset not found detail: Dataset not found application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' RateLimited: description: Rate Limit Exceeded headers: Retry-After: $ref: '#/components/headers/RetryAfter' Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Rate Limited application/problem+json: schema: $ref: '#/components/schemas/DetailedError' example: status: 429 type: https://api.honeycomb.io/problems/rate-limited title: You have exceeded your rate limit. error: You have exceeded your rate limit. detail: Please try again after 2025-02-01T15:23:12Z. application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' example: errors: - id: 06dcdd6508ca822f0e7e2bb4121c1f52 code: rate-limited/may-retry title: request rate limit exceeded detail: Please try again after 2025-02-01T15:23:12Z. GenericError: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' ```` Built with [Mintlify](https://mintlify.com).