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. externalDocs: url: https://docs.honeycomb.io servers: - url: https://api.honeycomb.io - url: https://api.eu1.honeycomb.io tags: - name: Anomaly Detection description: > Anomaly Detection is in public beta. Endpoints and response shapes may change. Anomaly Detection identifies Signals - patterns in your services that deviate from their historical baseline - and can notify Recipients when a Signal turns anomalous. Each Signal is scoped to a service in a dataset and monitors one of the following: - **`error_rate`**: The fraction of erroring requests, compared to a trained normal band. - **`presence`**: Whether the service is emitting spans at all. Signals progress through the following statuses: - **`onboarding`**: The Signal has been created but does not yet have enough data to train. - **`training`**: A baseline is being learned from recent traffic. - **`active`**: The Signal is trained and monitoring for anomalies. - **`off`**: The Signal has been disabled and will not fire. - **`ineligible`**: The Signal cannot train because its service is not sending enough traffic to establish a reliable baseline. This API allows you to list Signals, retrieve a Signal with its assigned Recipients, page through a Signal's historical anomalies, and update a Signal's enabled state, sensitivity, and Recipient assignments. ## Authorization The API key must have the **Manage Signals** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/). - 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/). paths: /1/auth: get: security: - configuration_key: [] - ingest_key: [] summary: List Authorizations description: > Returns metadata about the API Key used to call the API. Note: a Honeycomb Classic API key will return an empty string for both of the `environment` values. tags: - Auth operationId: getAuth responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Auth' examples: environment: description: Environment API Key value: id: FL_xMM5LapLC type: configuration api_key_access: events: true markers: true triggers: false boards: false queries: false columns: false createDatasets: true slos: false recipients: false privateBoards: false environment: name: Production slug: production team: name: Honeycomb Docs slug: honeycomb-docs classic: description: Classic Environment API Key value: id: A3jatwoWSxA type: configuration api_key_access: events: true markers: true triggers: false boards: false queries: false columns: false createDatasets: false slos: false recipients: false privateBoards: false environment: name: '' slug: '' team: name: Honeycomb Docs slug: honeycomb-docs ingest: description: Ingest API Key value: id: hcxik_01j1824es7n4evcmv81cn392jb type: ingest api_key_access: createDatasets: true environment: name: Production slug: production team: name: Honeycomb Docs slug: honeycomb-docs '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /2/auth: get: security: - bearerAuth: [] summary: List Authorizations V2 description: | Returns metadata about the Management API Key used to call the API. tags: - Auth operationId: getV2Auth responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/AuthV2Response' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' /1/boards: post: security: - configuration_key: [] summary: Create a Board description: | Create a Board comprised of one or more Panels (Query, SLO, or Text). **Note**: Each board is limited to a maximum of 5 preset filters. tags: - Boards operationId: createBoard requestBody: content: application/json: schema: $ref: '#/components/schemas/Board' examples: Simple Flexible Board with Query and Text Panels: value: name: My API Board description: A board created via the API with mixed panel types type: flexible panels: - type: query query_panel: query_id: abc1234e query_annotation_id: e4c24a35 position: x_coordinate: 0 y_coordinate: 0 height: 6 width: 8 - type: text text_panel: content: |- # Welcome to our API Dashboard This board shows key metrics for our services. position: x_coordinate: 8 y_coordinate: 0 height: 3 width: 4 layout_generation: manual tags: - key: team value: backend - key: environment value: production Auto-Layout Board with Multiple Panel Types: value: name: Service Health Overview description: Comprehensive service monitoring dashboard type: flexible panels: - type: query query_panel: query_id: def5678f query_annotation_id: a1b2c3d4 dataset: frontend-logs - type: slo slo_panel: slo_id: BGfyxhFto - type: text text_panel: content: |- ## Service Status ⚠️ **Note**: All services are currently operational layout_generation: auto tags: - key: service value: user-service required: true responses: '201': description: Created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Board' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' get: security: - configuration_key: [] summary: List All Boards description: > Retrieves a list of all non-secret Boards within an environment. **Note**: For Honeycomb Classic users, all boards within Classic will be returned. tags: - Boards operationId: listBoards 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/Board' examples: Mixed Board Types: value: - id: abc123 name: Production Monitoring description: Key metrics for production environment type: flexible panels: - type: query query_panel: query_id: ghi9012a query_annotation_id: f5e6d7c8 position: x_coordinate: 0 y_coordinate: 0 height: 6 width: 12 - type: text text_panel: content: |- # Production Status All systems operational position: x_coordinate: 0 y_coordinate: 6 height: 2 width: 12 layout_generation: manual tags: - key: environment value: production - id: def456 name: Service Health Dashboard description: SLO monitoring for critical services type: flexible panels: - type: slo slo_panel: slo_id: dF1URaPGL - type: query query_panel: query_id: jkl3456b query_annotation_id: b9c8d7e6 dataset: api-logs layout_generation: auto tags: - key: team value: platform '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/boards/{boardId}: parameters: - name: boardId description: The unique identifier (ID) of a Board. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Board description: Get a single Board by ID. tags: - Boards operationId: getBoard responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Board' examples: Flexible Board with All Panel Types: value: id: board789 name: Comprehensive Dashboard description: Complete monitoring setup with all panel types type: flexible panels: - type: query query_panel: query_id: stu5678e query_annotation_id: e9f8g7h6 dataset: application-logs position: x_coordinate: 0 y_coordinate: 0 height: 8 width: 8 - type: slo slo_panel: slo_id: BGfyxhFto position: x_coordinate: 8 y_coordinate: 0 height: 4 width: 4 - type: text text_panel: content: |- ## Alert Status 🟢 All systems normal **Last updated:** 2024-01-15 14:30 UTC position: x_coordinate: 8 y_coordinate: 4 height: 4 width: 4 layout_generation: manual tags: - key: criticality value: high - key: owner value: sre-team '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' put: security: - configuration_key: [] summary: Update a Board description: > Update a Board by specifying its ID and full details. **Note**: Queries can be added to, removed from, and re-ordered by updating the board itself. It is not possible to reference individual queries via the API. **Note**: Each board is limited to a maximum of 5 preset filters. Attempting to update a board with more than 5 preset filters will result in an error. tags: - Boards operationId: updateBoard requestBody: content: application/json: schema: $ref: '#/components/schemas/Board' examples: Add New Panel to Existing Board: value: id: board456 name: Updated Production Dashboard description: Production monitoring with additional SLO panel type: flexible panels: - type: query query_panel: query_id: cdef7890 query_annotation_id: h9i8j7k6 position: x_coordinate: 0 y_coordinate: 0 height: 6 width: 6 - type: slo slo_panel: slo_id: BGfyxhFto position: x_coordinate: 6 y_coordinate: 0 height: 6 width: 6 - type: text text_panel: content: |- ## Recent Changes - Added SLO monitoring - Updated query filters position: x_coordinate: 0 y_coordinate: 6 height: 3 width: 12 layout_generation: manual tags: - key: environment value: production - key: updated_by value: api Reorganize Panel Layout: value: id: board789 name: Service Metrics Reorganized description: Restructured layout for better visibility type: flexible panels: - type: query query_panel: query_id: ghij1234 query_annotation_id: i1j2k3l4 dataset: service-metrics - type: query query_panel: query_id: klmn5678 query_annotation_id: j5k6l7m8 dataset: error-logs - type: text text_panel: content: |- # Service Health Overview Monitoring key performance indicators layout_generation: auto tags: - key: team value: backend required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Board' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' delete: security: - configuration_key: [] summary: Delete a Board description: Delete a public Board by specifying its ID. tags: - Boards operationId: deleteBoard responses: '204': description: Success - no Content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/boards/{boardId}/views: parameters: - name: boardId description: The unique identifier (ID) of a Board. in: path required: true schema: type: string get: security: - configuration_key: [] summary: List Board Views description: | Retrieve a list of all views for a board. **Note**: Each board is limited to a maximum of 50 views. tags: - Boards operationId: listBoardViews responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: type: array maxItems: 50 items: $ref: '#/components/schemas/BoardViewResponse' examples: Multiple Views: value: - id: eC_abc123 name: Errors View filters: - column: status operation: '=' value: error - id: yc_def456 name: Slow requests view filters: - column: duration_ms operation: '>' value: 1000 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' post: security: - configuration_key: [] summary: Create a Board View description: > Create a new view for a board with the specified filters. **Note**: Each board is limited to a maximum of 50 views. Attempting to create more than 50 views will result in an error. tags: - Boards operationId: createBoardView requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBoardViewRequest' examples: Create board view for error statuses: value: name: Errors View filters: - column: status operation: '=' value: error responses: '201': description: Created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/BoardViewResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/boards/{boardId}/views/{viewId}: parameters: - name: boardId description: The unique identifier (ID) of a Board. in: path required: true schema: type: string - name: viewId description: The unique identifier (ID) of a Board View. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Board View description: Retrieve a single Board View by ID. tags: - Boards operationId: getBoardView responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/BoardViewResponse' examples: Single View with Multiple Filters: value: id: eC_abc123 name: Api and web slow requests errors filters: - column: status operation: '=' value: error - column: duration_ms operation: '>' value: 100 - column: service operation: in value: - api - web '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' delete: security: - configuration_key: [] summary: Delete a Board View description: Delete a Board View by specifying its ID. tags: - Boards operationId: deleteBoardView responses: '204': description: Success - no Content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' put: security: - configuration_key: [] summary: Update a Board View description: Update a Board View by specifying its ID and full details. tags: - Boards operationId: updateBoardView requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateBoardViewRequest' examples: Update board view for error statuses: value: name: Errors View filters: - column: status operation: '=' value: error responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/BoardViewResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/maps/dependencies/requests: post: security: - configuration_key: [] summary: Create a Map Dependency Request description: | Create a Map Dependency Request. tags: - Service Maps operationId: createMapDependencyRequest parameters: - name: limit in: query required: false description: > Maximum number of dependencies to return. Default is 10000, maximum is 64000. schema: type: integer minimum: 1 maximum: 64000 default: 10000 example: 5000 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateMapDependenciesRequest' examples: Get all depenedencies for last 2 hours for the user-service: value: time_range: 7200 filters: - name: user-service type: service Get dependencies for last 1 day starting from 2025-07-01: value: time_range: 86400 start_time: 1751328000 required: false responses: '200': description: >- Success - Results are ready or request has failed (see `status` field) headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' Location: schema: type: string description: >- The Location header will contain the URL where the results can be fetched. example: >- https://api.honeycomb.io/1/maps/dependencies/requests/HprJhV1fYyr Last-Modified: schema: type: string description: >- The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified. content: application/json: schema: $ref: '#/components/schemas/CreateMapDependenciesResponse' '201': description: Created - Request is pending headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' Location: schema: type: string description: >- The Location header will contain the URL where the results can be fetched. example: >- https://api.honeycomb.io/1/maps/dependencies/requests/HprJhV1fYyr Last-Modified: schema: type: string description: >- The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified. content: application/json: schema: $ref: '#/components/schemas/CreateMapDependenciesResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/maps/dependencies/requests/{requestId}: parameters: - name: requestId description: The unique identifier (ID) of a Map Dependencies Request. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get Map Dependencies description: > Get the dependencies for a previously created Map Dependencies Request. Note: This endpoint returns a single page of results and uses pagination. Even if you specified a large limit in the initial POST request, you will receive up to the page size limit per request and must use the pagination links to retrieve additional results. tags: - Service Maps operationId: getMapDependencies parameters: - $ref: '#/components/parameters/PaginationCursor' - $ref: '#/components/parameters/PaginationSize' responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' Last-Modified: schema: type: string description: >- The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified. Cache-Control: schema: type: string description: Cache-Control header is set for ready responses. content: application/json: schema: $ref: '#/components/schemas/GetMapDependenciesResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/burn_alerts/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create a Burn Alert description: | Create a Burn Alert against a specified SLO. tags: - Burn Alerts operationId: createBurnAlert requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBurnAlertRequest' required: true responses: '201': description: Created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/BurnAlertDetailResponse' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' get: security: - configuration_key: [] summary: List All Burn Alerts for an SLO description: > Get all burn alerts associated with the SLO specified in the `slo_id` query param. It is not currently possible to retrieve all burn alerts for a dataset, environment, or team. tags: - Burn Alerts operationId: listBurnAlertsBySlo parameters: - in: query name: slo_id schema: type: string description: >- For use with the list endpoint to retrieve all burn alerts for a specified SLO. required: true 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/BurnAlertListResponse' example: - id: fS7vfB81Wcy alert_type: exhaustion_time description: Use this runbook (link) if this alert fires. triggered: true exhaustion_minutes: 120 slo: id: 2LBq9LckbcA created_at: '2022-09-22T17:32:11Z' updated_at: '2022-10-22T17:32:11Z' - id: gT7wgC82Xcz alert_type: budget_rate description: Use this runbook (link) if this alert fires. triggered: true budget_rate_window_minutes: 60 budget_rate_decrease_threshold_per_million: 1000 slo: id: 2LBq9LckbcA created_at: '2022-09-22T17:32:11Z' updated_at: '2022-10-22T17:32:11Z' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/burn_alerts/{datasetSlug}/{burnAlertId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: burnAlertId description: The unique identifier (ID) of a Burn Alert. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Burn Alert description: | Get a single Burn Alert by ID. tags: - Burn Alerts operationId: getBurnAlert responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/BurnAlertDetailResponse' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' put: security: - configuration_key: [] summary: Update a Burn Alert description: | Update a Burn Alert by specifying its ID and full details. tags: - Burn Alerts operationId: updateBurnAlert requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateBurnAlertRequest' responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/BurnAlertDetailResponse' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' delete: security: - configuration_key: [] summary: Delete a Burn Alert description: Delete a Burn Alert by specifying its ID. tags: - Burn Alerts operationId: deleteBurnAlert responses: '204': description: Success - no content '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/datasets: post: security: - configuration_key: [] summary: Create a Dataset description: > Create a Dataset in the environment associated with your API key. If a Dataset already exists by that name (or slug), then the existing dataset will be returned. tags: - Datasets operationId: createDataset requestBody: description: > The dataset will be created within the environment associated with your API key. content: application/json: schema: $ref: '#/components/schemas/DatasetCreationPayload' required: true responses: '200': description: OK - Dataset already exists headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Dataset' '201': description: Created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Dataset' example: name: MyDataset! slug: mydataset- description: A nice description of my dataset expand_json_depth: 3 created_at: 2022-07-21T18:39:23.000Z last_written_at: null regular_columns_count: 0 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: Conflict headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: we could not create a dataset with that name application/problem+json: schema: $ref: '#/components/schemas/DetailedError' example: status: 409 type: https://api.honeycomb.io/problems/conflict title: >- Request could not be completed due to a conflict with the current state of the target resource. detail: environment has reached the maximum number of datasets allowed error: environment has reached the maximum number of datasets allowed '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' get: security: - configuration_key: [] summary: List All Datasets description: > Lists all Datasets for an environment. **Note**: For Honeycomb Classic users, all datasets in Classic are returned. tags: - Datasets operationId: listDatasets 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/Dataset' example: - name: my dataset! description: my dataset described! slug: my-dataset- expand_json_depth: 2 created_at: '2022-07-21T18:39:23Z' last_written_at: '2022-07-22T19:52:00Z' regular_columns_count: 12 - name: another dataset description: '' slug: another-dataset expand_json_depth: 0 created_at: '2022-07-21T18:39:23Z' last_written_at: '2022-07-22T19:52:00Z' regular_columns_count: 98 '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/datasets/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlug' get: security: - configuration_key: [] summary: Get a Dataset description: | Get a single Dataset by slug. tags: - Datasets operationId: getDataset responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Dataset' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' delete: security: - configuration_key: [] summary: Delete a Dataset description: > Deletes the Dataset. This is an irreversible operation. It may take several minutes for the deletion process to complete. **WARNING**: This endpoint will allow anyone with an API key that has the manage dataset permission to delete any dataset in the environment (or any dataset in the whole team for Classic customers). Datasets with Deletion Protection enabled cannot be deleted. To delete a Dataset with Deletion Protection enabled, first disable Deletion Protection by updating the Dataset with `settings.delete_protected = false`. tags: - Datasets operationId: deleteDataset responses: '202': description: Deleted headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' put: security: - configuration_key: [] summary: Update a Dataset description: | Update a Dataset's settings. tags: - Datasets operationId: updateDataset requestBody: description: > Update a Dataset's settings. All fields must be specified, as omitting one will have the effect of reverting the setting to the default. content: application/json: schema: $ref: '#/components/schemas/DatasetUpdatePayload' example: expand_json_depth: 3 description: my updated description settings: delete_protected: false responses: '200': description: Updated headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Dataset' example: name: My Dataset! slug: my-dataset- description: my updated description settings: delete_protected: false expand_json_depth: 3 created_at: '2022-07-21T18:39:23Z' last_written_at: '2022-09-22T17:32:03Z' regular_columns_count: 100 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' /1/batch/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlug' post: security: - configuration_key: [] - ingest_key: [] summary: Create Events description: > Supports batch creation of events. Dataset names are case insensitive. `POST` requests to "MyDatasET" will land in the same dataset as "mydataset". Names may contain URL-encoded spaces or other special characters, but not URL-encoded slashes. For example, "My%20Dataset" will show up in the UI as "My Dataset". The first event received for a dataset determines the casing of the displayed name. All subsequent variations in casing will use the originally specified case. tags: - Events operationId: createEvents parameters: - in: header name: Content-Encoding description: > Included when sending events in a file. Size limitations may be addressed by compressing request bodies with gzip or zstd compression. Be sure to set the Content-Encoding to `gzip` or `zstd` when compressing the request body. If sending plaintext, omit this header; "plaintext" is included to simplify the example with curl. schema: type: string enum: - gzip - zstd example: plaintext requestBody: required: true description: > The array should contain one or more JSON objects representing Events. Each Event contains its payload under the `data` key. Values of `time` and/or `samplerate` can be included as well. The JSON payload should have the structure: `[{ "data": { "key1": "value1", "key2": 2.0 } }, ... ]` Size limitations may be addressed by compressing request bodies with `gzip` or `zstd` compression. An empty `202` response indicates that the event has been queued for processing. content: application/json: schema: type: array items: $ref: '#/components/schemas/BatchEvent' example: - time: '2006-01-02T15:04:05.99Z' samplerate: 1 data: method: GET endpoint: /foo shard: users duration_ms: 32 - time: '2006-01-02T15:04:05.99Z' data: some_other_key: value duration_ms: 40 application/octet-stream: schema: type: string format: binary responses: '200': description: Enqueued for processing content: application/json: schema: type: array items: type: object properties: status: type: number error: type: string example: - status: 202 - status: 400 error: Request body should not be empty. - status: 400 error: Event has too many columns. - status: 400 error: Request body is malformed and cannot be read. '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: not-empty: description: The body is empty, or blank. value: error: Request body should not be empty. dataset-too-many-columns: description: The dataset has reached the maximum number of columns. value: error: Dataset has too many columns. malformed-request: description: The API failed to decode the body as JSON. value: error: Request body is malformed and cannot be read. too-large: description: The body is too large. value: error: Request body is too large. '401': $ref: '#/components/responses/Unauthorized' '403': description: Dropped due to administrative throttling content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Event dropped due to administrative throttling '404': $ref: '#/components/responses/NotFound' '429': description: Dropped due to rate limiting content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate-limiting: value: error: Request dropped due to rate limiting. deny-list: value: error: Event dropped due to administrative denylist /1/dataset_definitions/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlug' patch: security: - configuration_key: [] summary: Set or Update Dataset Definitions description: > Set or update one or more definitions for a Dataset. **Note**: While the PATCH payload can include the `column_type`, Honeycomb does not use this field when updating Dataset Definitions. tags: - Dataset Definitions operationId: patchDatasetDefinitions requestBody: description: > The PATCH payload takes a map of Dataset definition type to Dataset definition. Fields not defined in the request are not modified on the server. **Note**: In order to **CLEAR** a column of a Dataset definition set the column’s name field to an empty string. content: application/json: schema: $ref: '#/components/schemas/DatasetDefinitions' examples: setting: description: Set the duration_ms definition. value: duration_ms: name: duration_we_send column_type: derived_column clearing: description: Clear the definitions. value: error: name: '' link_trace_id: name: '' required: true responses: '200': description: Dataset Definitions have been updated headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/DatasetDefinitions' example: duration_ms: name: duration_ms column_type: column error: null name: null parent_id: null route: null service_name: null span_id: name: my_span_id column_type: column span_kind: null annotation_type: null link_trace_id: null link_span_id: null status: null trace_id: null user: null log_severity: null log_message: null '400': description: Bad Request headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/DetailedError' example: status: 400 type: https://api.honeycomb.io/problems/unparseable title: The request body could not be parsed. detail: could not parse request body error: could not parse request body '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': description: 422 Unprocessable Entity headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'The following columns were not found: duration_we_send' get: security: - configuration_key: [] summary: Get all Dataset Definitions description: > Get all definitions for a Dataset. The response returns an object with a Dataset Definition for each set Dataset Definition type. tags: - Dataset Definitions operationId: listDatasetDefinitions responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/DatasetDefinitions' example: duration_ms: name: duration_ms column_type: column error: null name: null parent_id: null route: null service_name: null span_id: name: my_span_id column_type: column span_kind: null annotation_type: null link_trace_id: null link_span_id: null status: null trace_id: null user: null log_severity: null log_message: null '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /1/events/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlug' post: security: - configuration_key: [] - ingest_key: [] summary: Create an Event description: > Using this endpoint for anything more than testing is highly discouraged. Sending events in batches will be much more efficient and should be preferred if at all possible. tags: - Events operationId: createEvent parameters: - in: header name: X-Honeycomb-Event-Time description: The Event's timestamp. Optional. Defaults to server time. schema: type: integer - in: header name: X-Honeycomb-Samplerate description: Optional. Defaults to 1. schema: type: integer requestBody: description: > The request body is limited to raw (potentially compressed) size of 1MB. The maximum number of distinct columns (fields) allowed in an event is `2000`. content: application/json: schema: $ref: '#/components/schemas/Event' example: method: GET endpoint: /foo shard: users duration_ms: 32 required: true responses: '200': description: Enqueued for processing '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: not-empty: description: The body is empty, or blank. value: error: Request body should not be empty. dataset-too-many-columns: description: The dataset has reached the maximum number of columns. value: error: Dataset has too many columns. events-too-many-columns: description: The event has reached the maximum number of columns. value: error: Event has too many columns. malformed-request: description: The API failed to decode the body as JSON. value: error: Request body is malformed and cannot be read. too-large: description: The body is too large. value: error: Request body is too large. '401': $ref: '#/components/responses/Unauthorized' '403': description: Dropped due to administrative throttling content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Event dropped due to administrative throttling '404': $ref: '#/components/responses/NotFound' '429': description: Dropped due to rate limiting content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate-limiting: value: error: Request dropped due to rate limiting. deny-list: value: error: Event dropped due to administrative denylist /1/kinesis_events/{datasetSlug}: parameters: - in: header name: X-Amz-Firehose-Request-Id description: | AWS Request ID associated with the Kinesis Firehose. schema: type: string required: true example: 33658b45-a8f1-4007-92e8-f601ae33db14 - $ref: '#/components/parameters/datasetSlug' post: summary: Create Kinesis Events description: > This endpoint processes events and metrics coming from AWS through Kinesis Firehose. tags: - Kinesis Events operationId: createKinesisEvents security: - firehose_access_key: [] requestBody: description: > The request body expected from Amazon Kinesis Firehose. Events and metrics have the same shape but the base64 encoded data blob for metrics is expected to be Protowire-encoded as well. CloudWatch Logs data coming through Amazon Kinesis Firehose is expected to have a gzip Content-Encoding. content: application/json: schema: $ref: '#/components/schemas/KinesisEvent' required: true responses: '200': description: Events queued for processing content: application/json: schema: $ref: '#/components/schemas/KinesisResponse' '401': $ref: '#/components/responses/Unauthorized' default: $ref: '#/components/responses/GenericError' /1/markers/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create a Marker description: > Create a Marker in the specified dataset. To create an environment marker, use the `__all__` keyword and an API key associated with the desired environment. tags: - Markers operationId: createMarker requestBody: description: | The marker body can include as many of the Marker fields as desired. content: application/json: schema: $ref: '#/components/schemas/Marker' required: true responses: '201': description: Created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Marker' example: created_at: '2016-08-13T05:39:42Z' updated_at: '2016-08-13T05:39:42Z' start_time: 1471040808 message: 'backend deploy #123' type: deploy id: d1c84ec0 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' get: security: - configuration_key: [] summary: List All Markers description: | Lists all Markers for a dataset. tags: - Markers operationId: getMarker 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/Marker' example: - created_at: '2016-08-13T05:39:42Z' updated_at: '2016-08-13T05:39:42Z' start_time: 1471040808 message: 'backend deploy #123' type: deploy id: d1c84ec0 - created_at: '2016-08-14T05:39:42Z' updated_at: '2016-08-14T05:39:42Z' start_time: 1471040808 message: 'frontend deploy #123' type: deploy id: c2b52fa0 '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/markers/{datasetSlug}/{markerId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: markerId description: The unique identifier (ID) of a Marker. in: path required: true schema: type: string put: security: - configuration_key: [] summary: Update a Marker description: > Update a Marker in the specified dataset. To update an environment marker, use the `__all__` keyword and an API key associated with the desired environment. tags: - Markers operationId: updateMarker requestBody: description: > If an existing field is not included in the payload, it will be erased. content: application/json: schema: $ref: '#/components/schemas/Marker' required: true responses: '200': description: Updated headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Marker' example: created_at: '2016-08-13T05:39:42Z' updated_at: '2016-08-13T05:39:42Z' start_time: 1471040808 message: 'backend deploy #123' type: deploy id: d1c84ec0 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' delete: security: - configuration_key: [] summary: Delete a Marker tags: - Markers operationId: deleteMarker responses: '200': description: | Success The deleted Marker will be in the body of the response. headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Marker' example: created_at: '2016-08-13T05:39:42Z' updated_at: '2016-08-13T05:39:42Z' start_time: 1471040808 message: 'backend deploy #123' type: deploy id: d1c84ec0 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/marker_settings/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create a Marker Setting tags: - Marker Settings operationId: createMarkerSetting requestBody: content: application/json: schema: $ref: '#/components/schemas/MarkerSetting' required: true responses: '201': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/MarkerSetting' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' get: security: - configuration_key: [] summary: Get a Marker Setting tags: - Marker Settings operationId: listMarkerSettings 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/MarkerSetting' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' /1/marker_settings/{datasetSlug}/{markerSettingId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: markerSettingId description: The unique identifier (ID) of a marker setting. in: path required: true schema: type: string put: security: - configuration_key: [] summary: Update a Marker Setting description: | A marker setting's `type` may not be changed after creation. tags: - Marker Settings operationId: updateMarkerSettings requestBody: content: application/json: schema: $ref: '#/components/schemas/MarkerSetting' example: type: deploy color: '#1fa297' required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/MarkerSetting' example: type: deploy color: '#1fa297' id: gwAHiE5TS4j created_at: '2022-09-15T05:39:42Z' updated_at: '2022-12-20T08:10:05Z' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' delete: security: - configuration_key: [] summary: Delete a Marker Setting tags: - Marker Settings operationId: deleteMarkerSettings responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/MarkerSetting' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' /1/queries/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create a Query description: > Create a query from a specification. DOES NOT run the query to retrieve results. tags: - Queries operationId: createQuery requestBody: content: application/json: schema: $ref: '#/components/schemas/Query' examples: Simple Query: value: calculations: - op: COUNT orders: - op: COUNT order: descending time_range: 7200 Query With Filter and Group By: value: calculations: - op: COUNT breakdowns: - user_agent filters: - op: '>=' column: response.status_code value: 400 orders: - op: COUNT order: descending time_range: 7200 Query With Filter and Calculated Fields: value: calculations: - op: COUNT breakdowns: - response.status_code filters: - op: '=' column: adhoc_check value: true calculated_fields: - name: adhoc_check expression: GT($response.status_code, 200) orders: - op: COUNT order: descending time_range: 7200 Query With Relational Fields: value: calculations: - op: COUNT breakdowns: - name - root.response.status_code filters: - op: '=' column: child.response.status_code value: 400 orders: - op: COUNT order: descending time_range: 3600 compare_time_offset_seconds: 86400 required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Query' examples: Simple Query: value: id: abc3419d calculations: - op: COUNT orders: - op: COUNT order: descending time_range: 7200 Query With Filter and Group By: value: id: xyz321a calculations: - op: COUNT breakdowns: - user_agent filters: - op: '>=' column: response.status_code value: 400 orders: - op: COUNT order: descending time_range: 7200 Query With Filter and Calculated Fields: value: id: lmn098p calculations: - op: COUNT breakdowns: - response.status_code filters: - op: '=' column: adhoc_check value: true calculated_fields: - name: adhoc_check expression: GT($response.status_code, 200) orders: - op: COUNT order: descending time_range: 7200 Query With Relational Fields: value: id: abc3419d calculations: - op: COUNT breakdowns: - name - root.response.status_code filters: - op: '=' column: child.response.status_code value: 400 orders: - op: COUNT order: descending time_range: 3600 compare_time_offset_seconds: 86400 '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' /1/queries/{datasetSlug}/{queryId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: queryId description: The unique identifier (ID) of a query. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Query description: | Retrieve a query by its ID. tags: - Queries operationId: getQuery responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Query' example: id: abc3419d breakdowns: - user_agent calculations: - op: COUNT orders: - op: COUNT order: descending limit: 10 time_range: 7200 end_time: 1676467828 '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' /1/query_annotations/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create a Query Annotation description: | Create a Query Annotation for the specified query ID. tags: - Query Annotations operationId: createQueryAnnotation requestBody: content: application/json: schema: $ref: '#/components/schemas/QueryAnnotation' required: true responses: '201': description: Created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/QueryAnnotation' '400': description: Bad Request headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid-query-id: description: The query ID is invalid. value: error: Query ID included in body is invalid '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' get: security: - configuration_key: [] summary: List Query Annotations description: | List all Query Annotations in the specified dataset. tags: - Query Annotations operationId: listQueryAnnotations parameters: - name: include_board_annotations in: query description: > Whether to include Query Annotations that were created from boards. By default, only Query Annotations created directly from queries are returned. schema: type: boolean default: false required: false 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/QueryAnnotation' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/query_annotations/{datasetSlug}/{queryAnnotationId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: queryAnnotationId description: The unique identifier (ID) of the annotation. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Query Annotation description: | Get a Query Annotation by its ID. tags: - Query Annotations operationId: getQueryAnnotation responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/QueryAnnotation' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' put: security: - configuration_key: [] summary: Update a Query Annotation description: > Update a Query Annotation by specifying its ID. The Query ID associated with the Query Annotation cannot be updated. Partial updates are not supported. tags: - Query Annotations operationId: updateQueryAnnotation requestBody: content: application/json: schema: $ref: '#/components/schemas/QueryAnnotation' example: name: My Updated Annotation description: A nice description of My Update Annotation query_id: mabAMpSPDjH id: sGUnkBHgRFN created_at: '2022-10-26T21:36:04Z' updated_at: '2022-12-16T10:44:08Z' required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/QueryAnnotation' example: name: My Updated Annotation description: A nice description of My Update Annotation query_id: mabAMpSPDjH '400': description: Bad Request headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' examples: update-includes-bad-id: description: >- The ID in the URL and the ID in the request body do not match. value: error: Query annotation id included in body does not match URL invalid-query-id: description: The query ID is invalid. value: error: Query id included in body is invalid cannot-update-query-id: description: The query ID cannot be updated. value: error: queries in annotations cannot be changed query-not-in-dataset: description: The query ID does not exist in the specified dataset. value: error: Query is not in the dataset '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' delete: security: - configuration_key: [] summary: Delete a Query Annotation description: | Delete a Query Annotation by specifying its ID. tags: - Query Annotations operationId: deleteQueryAnnotation responses: '204': description: Success - no content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/query_results/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create a Query Result description: > Kick off processing of a Query to then get back the Query Results. Once the Query Result has been created, the query will be run asynchronously, allowing the result data to be fetched from the GET query result endpoint. A maximum duration of 7 days of data can be queried. Any queries with a `start_time`, `end_time`, or `time_range` resulting in a duration longer than 7 days will result in a `400` error response. tags: - Query Data operationId: createQueryResult requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateQueryResultRequest' required: true responses: '201': description: Created headers: Location: schema: type: string description: >- The Location header will contain the URL where the results can be fetched. example: >- https://api.honeycomb.io/1/query_results/test-via-curl/HprJhV1fYyr content: application/json: schema: $ref: '#/components/schemas/QueryResult' examples: Simple Query: value: query: calculations: - op: COUNT orders: - op: COUNT order: descending limit: 10000 time_range: 7200 complete: false id: dfg456 links: query_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/dfg456 graph_image_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/dfg456/snapshot Query with Filter and Group By: value: query: calculations: - op: COUNT breakdowns: - user_agent filters: - op: '>=' column: response.status_code value: 400 orders: - op: COUNT order: descending limit: 10000 time_range: 7200 complete: false id: hij678a links: query_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/hij678a graph_image_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/hij678a/snapshot '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': description: Rate Limit Exceeded content: 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: This endpoint allows 10 requests per minute. default: $ref: '#/components/responses/GenericError' /1/query_results/{datasetSlug}/{queryResultId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: queryResultId description: The unique identifier (ID) of the query result. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get Query Result description: > Get the Query Result details for a specific Query Result ID. This endpoint is used to fetch the results of a query that had previously been created. It is recommended to follow the Location header included in the Create Query Result output, but the URL can also be constructed manually with the <query-result-id>. Note: a query that fails to run still returns HTTP 200. Check the response body: a failed query has "complete": true with an "error" field in place of "data". tags: - Query Data operationId: getQueryResult responses: '200': description: Success headers: Last-Modified: schema: type: string description: >- The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified. example: Mon, 02 Jan 2006 15:04:05 GMT Cache-Control: schema: type: string description: >- The max-age=N response directive indicates that the response remains fresh until N seconds after the response is generated. example: private, max-age=86400 content: application/json: schema: $ref: '#/components/schemas/QueryResultDetails' examples: Simple Query: value: query: calculations: - op: COUNT orders: - op: COUNT order: descending limit: 10000 time_range: 7200 complete: true id: dfg456 data: series: [] results: - data: COUNT: 20769 links: query_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/dfg456 graph_image_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/dfg456/snapshot Query with Filter and Group By: value: query: calculations: - op: COUNT breakdowns: - user_agent filters: - op: '>=' column: response.status_code value: 400 orders: - op: COUNT order: descending limit: 10000 time_range: 7200 complete: false id: hij678a data: series: [] results: - data: COUNT: 2728 user_agent: Mozilla/5.0 (X11; Linux x86_64) - data: COUNT: 4 user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) - data: COUNT: 7 user_agent: >- Mozilla/5.0 (Linux; Android 7.1.2; AFTMM Build/NS6265; wv) links: query_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/hij678a graph_image_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/hij678a/snapshot Failed Query: description: The query failed to run, so "error" replaces "data". value: query: calculations: - op: COUNT orders: - op: COUNT order: descending limit: 10000 time_range: 7200 complete: true id: klm901 error: we had trouble fetching your results! try again? links: query_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/klm901 graph_image_url: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/klm901/snapshot '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/GenericError' /1/recipients: post: security: - configuration_key: [] summary: Create a Recipient description: > Unlike many resources, Recipients are not linked to a specific Environment or Dataset. The Recipient will be created for the Team associated with your API key. The `details` fields will vary depending on the `type` of Recipient. Use the drop-down to view the specific fields for each `type` value. Before Slack Recipients can be created, the Slack OAuth flow in the Integration Center must be completed. tags: - Recipients operationId: createRecipient requestBody: content: application/json: schema: $ref: '#/components/schemas/Recipient' required: true responses: '201': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Recipient' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' get: security: - configuration_key: [] summary: List all Recipients description: | Retrieve all recipients for a team. tags: - Recipients operationId: listRecipients 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/Recipient' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unknown API key - check your credentials /1/recipients/{recipientId}: parameters: - $ref: '#/components/parameters/recipientId' get: security: - configuration_key: [] summary: Get a single Recipient description: | Retrieve a Recipient by recipient ID. tags: - Recipients operationId: getRecipient responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Recipient' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: security: - configuration_key: [] summary: Update a Recipient description: > Update a Recipient by specifying the recipient ID and full recipient details. (Partial PUT is not supported.) Updates to the Recipient Type is not supported. For example, changing an existing Recipient from PagerDuty to Email is not allowed. **Important**: Modifying an existing recipient will change the destination of all triggers/burn alerts that use that recipient. tags: - Recipients operationId: updateRecipient requestBody: content: application/json: schema: $ref: '#/components/schemas/Recipient' required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Recipient' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' delete: security: - configuration_key: [] summary: Delete a Recipient description: > Delete a recipient by specifying the recipient ID. A Recipient can only be deleted if it is NOT in use by any Triggers or Burn Alerts associated to the team. tags: - Recipients operationId: deleteRecipient responses: '204': description: Success - no content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unknown API key - check your credentials '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' /1/slos/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create an SLO description: | Create an SLO on the provided dataset. tags: - SLOs operationId: createSlo requestBody: content: application/json: schema: $ref: '#/components/schemas/SLOCreate' required: true responses: '201': description: Success - SLO created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/SLOCreate' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' get: security: - configuration_key: [] summary: Get all SLOs description: > Get all SLOs for a dataset or environment (using `__all__`). This action returns any SLOs, including those applied with multiple datasets. tags: - SLOs operationId: listSlos 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/SLO' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/slos/{datasetSlug}/{sloId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: sloId description: Unique identifier (ID) of the SLO. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get an SLO description: | Get an SLO by ID. tags: - SLOs operationId: getSlo parameters: - in: query name: detailed schema: type: boolean description: > Allows SLO reporting data (`status`, `burn_rate`, `budget_remaining` and `compliance`) to be returned when retrieving a single SLO. This feature is available as part of the [Honeycomb Enterprise plan](https://www.honeycomb.io/pricing/). **Note:** `burn_rate` is calculated based on the last 4 hours of data. required: false allowEmptyValue: true example: '' responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: anyOf: - $ref: '#/components/schemas/SLO' - $ref: '#/components/schemas/SLODetailedResponse' examples: get-slo: description: Get an SLO by ID value: id: bZ1aRHAUsjG name: My SLO description: My SLO description sli: alias: my-sli time_period_days: 30 target_per_million: 989900 reset_at: '2022-10-15T13:53:11Z' created_at: '2022-09-15T05:39:42Z' updated_at: '2022-12-20T08:10:05Z' dataset_slugs: - mydataset1 get-slo-detailed: description: Get SLO by ID with detailed response value: id: bZ1aRHAUsjG name: My SLO description: My SLO description sli: alias: my-sli time_period_days: 30 target_per_million: 989900 compliance: 95.39 budget_remaining: 7.73 status: normal burn_rate: 5.39 reset_at: '2022-10-15T13:53:11Z' created_at: '2022-09-15T05:39:42Z' updated_at: '2022-12-20T08:10:05Z' dataset_slugs: - mydataset1 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' put: security: - configuration_key: [] summary: Update an SLO description: | Update an SLO by specifying its ID and full SLO details. tags: - SLOs operationId: updateSlo requestBody: description: | Partial updates are not supported. content: application/json: schema: $ref: '#/components/schemas/SLO' required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/SLO' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' delete: security: - configuration_key: [] summary: Delete an SLO description: | Delete an SLO by specifying its ID. tags: - SLOs operationId: deleteSlo responses: '204': description: Success - no content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/slos/{datasetSlug}/{sloId}/counts: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: sloId description: Unique identifier (ID) of the SLO. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get SLO Realtime Counts description: > Get per-minute success and failure event counts for an SLO, updated approximately once per minute from a rolling 24-hour window. This endpoint is intended for near-real-time integrations such as external SLO dashboards and alerting tools (e.g. nobl9). For weekly compliance history, use the [Get SLO History endpoint](https://api-docs.honeycomb.io/api/reporting/getSloHistory/). **Requirements:** - Available on the [Enterprise plan](https://www.honeycomb.io/pricing/) only. - This feature must be enabled for your team. Contact your account team to request access. **Gaps:** Some minutes may have no entry in the `windows` array. The first window after a gap may contain a larger-than-usual delta. Treat missing timestamps as unavailable data, not zero-event periods. **Epoch:** The response includes an `epoch` field — a hash of the SLO's SLI expression and dataset configuration. If this value changes between responses, the underlying SLO definition has changed and any client-side cache should be invalidated. **Partial windows:** Windows marked `is_partial: true` may still receive additional events. This occurs for the most recent 10 minutes (late-arriving data settlement) or when no prior snapshot exists to compute a delta from. tags: - SLOs operationId: getSloRealtimeCounts parameters: - in: query name: start_time required: true schema: type: integer description: > Start of the time range as a Unix timestamp (seconds). Must be within the last 24 hours and no later than `end_time`. example: 1745251200 - in: query name: end_time required: true schema: type: integer description: > End of the time range as a Unix timestamp (seconds). Must be greater than `start_time` and within the same clock hour as `start_time`. Realtime counts accumulate from the start of each hour and reset at hour boundaries; use the [Get SLO Hourly Counts History endpoint](https://api-docs.honeycomb.io/api/slos/getSloHourlyCountsHistory/) for completed hours. example: 1745254740 responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/SLOCountsResponse' example: slo_id: bZ1aRHAUsjG resolution_seconds: 60 epoch: a3f9c2d1e8b74056 period_start: 1745251200 windows: - window_start: 1745251200 window_end: 1745251260 total_count: 1243 error_count: 3 is_partial: false - window_start: 1745251260 window_end: 1745251320 total_count: 1188 error_count: 1 is_partial: false - window_start: 1745251320 window_end: 1745251380 total_count: 1301 error_count: 0 is_partial: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/slos/{datasetSlug}/{sloId}/counts/history: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: sloId description: Unique identifier (ID) of the SLO. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get SLO Hourly Counts History description: > Get hourly-bucketed total and error event counts for an SLO from the persistent historical store. Use this endpoint to retrieve completed historical hours; pair with the [Get SLO Realtime Counts endpoint](https://api-docs.honeycomb.io/api/slos/getslorealtimecounts/) for the current in-progress hour. **Requirements:** - Available on the [Enterprise plan](https://www.honeycomb.io/pricing/) only. - This feature must be enabled for your team. Contact your account team to request access. **Partial buckets:** The most recent bucket may be marked `is_partial: true` if it covers the current in-progress hour. Counts for that bucket will increase until the hour completes. tags: - SLOs operationId: getSloHourlyCountsHistory parameters: - in: query name: start_time required: true schema: type: integer description: | Start of the time range as a Unix timestamp (seconds). example: 1745168400 - in: query name: end_time required: true schema: type: integer description: > End of the time range as a Unix timestamp (seconds). Must be greater than `start_time`. example: 1745254800 responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/SLOHourlyCountsResponse' example: slo_id: bZ1aRHAUsjG resolution_seconds: 3600 buckets: - start_time: 1745168400 end_time: 1745172000 total_count: 74520 error_count: 182 is_partial: false - start_time: 1745172000 end_time: 1745175600 total_count: 71043 error_count: 97 is_partial: false - start_time: 1745251200 end_time: 1745254800 total_count: 12300 error_count: 14 is_partial: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/reporting/slos/historical: post: security: - configuration_key: [] summary: Get SLO History description: > Get a weekly breakdown of historical data for a list of SLOs for a given time range. tags: - Reporting operationId: getSloHistory requestBody: content: application/json: schema: $ref: '#/components/schemas/SLOHistoryRequest' required: true responses: '200': description: > A mapping from SLO IDs (e.g., "2LBq9LckbcA") to their historical data. Each SLO ID maps to an array of compliance and budget intervals. **Note**: An empty array indicates that no historical data was found for the given time range for that SLO. headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/SLOHistoryResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' default: $ref: '#/components/responses/GenericError' /1/signals: get: security: - configuration_key: [] summary: List All Signals description: > List Signals in the environment associated with your API key. Signals are returned in cursor-paginated pages and can be filtered by service, dataset, kind, status, and whether they are currently anomalous. tags: - Anomaly Detection operationId: listSignals x-mint: metadata: tag: Beta parameters: - $ref: '#/components/parameters/PaginationCursor' - $ref: '#/components/parameters/PaginationSize' - in: query name: service_name description: Restrict results to Signals for a single service. schema: type: string example: checkout-api - in: query name: dataset_slug description: Restrict results to Signals in a single dataset. schema: type: string example: checkout-api - in: query name: signal description: Restrict results to Signals of the given kind. schema: $ref: '#/components/schemas/AnomalySignal' - in: query name: status description: | Restrict results to Signals in the given status. schema: type: string enum: - onboarding - training - active - ineligible - false - in: query name: currently_anomalous description: >- When `true`, only return Signals that are currently in an anomalous state. schema: type: boolean responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/PaginatedSignalsResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/signals/{id}: parameters: - name: id description: The unique identifier (ID) of a Signal. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Signal description: | Fetch a Signal by ID, including the Recipients assigned to it. tags: - Anomaly Detection operationId: getSignal x-mint: metadata: tag: Beta responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/SignalDetailResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' put: security: - configuration_key: [] summary: Update a Signal description: > Update a Signal by ID. All fields in the body are optional; only the fields you supply are applied. - `enabled`: Toggles the Signal on or off. Re-enabling a Signal that has already trained puts it back into `active`; otherwise it returns to `onboarding`. - `sensitivity`: Sets how far a measurement must deviate from the trained normal band before the Signal fires. Not applicable to `presence` Signals, and cannot be set on a Signal that has not yet trained. - `recipients`: Replaces the Signal's Recipient set. An empty array clears all Recipients. Modifying Recipients requires the **Manage Recipients** permission in addition to **Manage Signals**. tags: - Anomaly Detection operationId: updateSignal x-mint: metadata: tag: Beta requestBody: description: Fields to update on the Signal. All fields are optional. required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSignalRequest' responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/SignalDetailResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/signals/{id}/historical_anomalies: parameters: - name: id description: The unique identifier (ID) of a Signal. in: path required: true schema: type: string get: security: - configuration_key: [] summary: List Historical Anomalies description: > List anomalies that a Signal has resolved within a bounded time window. Anomalies are returned in cursor-paginated pages, most recent first. `start_time` and `end_time` are required and must span no more than 30 days. tags: - Anomaly Detection operationId: listSignalHistoricalAnomalies x-mint: metadata: tag: Beta parameters: - in: query name: start_time required: true description: Start of the query window, in seconds since UNIX epoch. schema: type: integer example: 1740787200 - in: query name: end_time required: true description: >- End of the query window, in seconds since UNIX epoch. Must be after `start_time` and within 30 days of it. schema: type: integer example: 1741392000 - $ref: '#/components/parameters/PaginationCursor' - $ref: '#/components/parameters/PaginationSize' responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/PaginatedHistoricalAnomaliesResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' /1/triggers/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' get: security: - configuration_key: [] summary: List All Triggers description: | List all triggers on the provided dataset or environment. tags: - Triggers operationId: listTriggers responses: '200': description: OK 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' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/GenericError' post: security: - configuration_key: [] summary: Create a Trigger description: | Create a trigger on the provided dataset or environment. tags: - Triggers operationId: createTrigger requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTriggerRequest' required: true responses: '201': description: Success - trigger created headers: Location: schema: type: string description: Relative path to fetch this trigger via API. Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/TriggerResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' /1/triggers/{datasetSlug}/{triggerId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: triggerId description: The unique identifier (ID) of a Trigger. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Trigger description: | Fetch details for a single Trigger by Trigger ID. tags: - Triggers operationId: getTrigger responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/TriggerResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' put: security: - configuration_key: [] summary: Update a Trigger description: > Update a trigger by specifying the trigger ID and the same fields used when creating a new trigger. tags: - Triggers operationId: updateTrigger requestBody: content: application/json: schema: $ref: '#/components/schemas/TriggerResponse' required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/TriggerResponse' '400': $ref: '#/components/responses/GenericError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' delete: security: - configuration_key: [] summary: Delete a Trigger description: > Delete a trigger by specifying the trigger ID. The body of the DELETE request should be empty. tags: - Triggers operationId: deleteTrigger responses: '204': description: Success - no content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' /1/recipients/{recipientId}/triggers: parameters: - $ref: '#/components/parameters/recipientId' get: security: - configuration_key: [] 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. tags: - Triggers 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' /1/derived_columns/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create a Calculated Field description: > Create a Calculated Field (also called a Derived Column). Calculated Fields allow you to run queries based on the value of an expression that is calculated from the fields in an event. tags: - Calculated Fields operationId: createCalculatedField requestBody: content: application/json: schema: $ref: '#/components/schemas/CalculatedField' required: true responses: '201': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/CalculatedField' example: id: yUheCUmgZ8p alias: one description: just one expression: INT(1) created_at: '2022-07-26T22:38:04Z' updated_at: '2022-11-16T17:34:01Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' get: security: - configuration_key: [] summary: List all Calculated Fields description: >- Get all the Calculated Fields (also called Derived Columns) in a dataset or environment. With the `?alias=X` query parameter, can return a single Calculated Field by its `alias`. tags: - Calculated Fields operationId: listCalculatedFields parameters: - name: alias description: The Calculated Field `alias`. in: query schema: type: string responses: '200': description: > When listing all columns, an array of CalculatedField objects will be returned. When using `key_name`, will return a single CalculatedField object if found. headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: oneOf: - $ref: '#/components/schemas/CalculatedFieldList' - $ref: '#/components/schemas/CalculatedField' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' /1/derived_columns/{datasetSlug}/{derivedColumnId}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' - name: derivedColumnId description: >- Unique identifier (ID) of a Calculated Field (also called a Derived Column). in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Calculated Field tags: - Calculated Fields operationId: getCalculatedField responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/CalculatedField' example: id: yUheCUmgZ8p alias: one description: just one expression: INT(1) created_at: '2022-07-26T22:38:04Z' updated_at: '2022-11-16T17:34:01Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' put: security: - configuration_key: [] summary: Update a Calculated Field description: | Update a Calculated Field (also called a Derived Column). tags: - Calculated Fields operationId: updateCalculatedField requestBody: content: application/json: schema: $ref: '#/components/schemas/CalculatedField' required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/CalculatedField' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' delete: security: - configuration_key: [] summary: Delete a Calculated Field description: > Delete a Calculated Field (also called a Derived Column). **Note**: A Calculated Field used by a SLO, Trigger, or Board cannot be deleted without removing or modifying the SLO, Trigger, or Board first. tags: - Calculated Fields operationId: deleteCalculatedField responses: '204': description: Success - no content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' /1/columns/{datasetSlug}: parameters: - $ref: '#/components/parameters/datasetSlugOrAll' post: security: - configuration_key: [] summary: Create a Column description: | Create a column by providing corresponding details for that type. tags: - Columns operationId: createColumn requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateColumn' required: true responses: '201': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Column' example: id: yUheCUmgZ8p key_name: my_column hidden: false description: An integer column type: integer last_written: '2022-07-26T22:38:05Z' created_at: '2022-07-26T22:38:04Z' updated_at: '2022-07-26T22:38:04Z' '400': description: Bad Request headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Key name cannot be blank '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' get: security: - configuration_key: [] summary: List all Columns description: > Get all the Columns in a dataset or environment. Use `__all__` as the dataset slug to retrieve all Columns across all datasets in the environment (not available for classic environments). tags: - Columns operationId: listColumns parameters: - name: key_name description: the column key name in: query schema: type: string responses: '200': description: > When listing all columns, an array of Column objects will be returned. When using `key_name`, will return a single Column object if found. headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: oneOf: - $ref: '#/components/schemas/ColumnList' - $ref: '#/components/schemas/Column' examples: list-of-columns: description: Lists all columns. value: - id: yUheCUmgZ8p key_name: my_column hidden: false description: '' type: integer last_written: '2022-07-26T22:38:05Z' created_at: '2022-07-26T22:38:04Z' updated_at: '2022-07-26T22:38:04Z' - id: yUheCUmgZ8q key_name: other_column hidden: false description: '' type: string last_written: '2022-07-26T22:38:05Z' created_at: '2022-07-26T22:38:04Z' updated_at: '2022-07-26T22:38:04Z' get-column-by-key-name: description: Get back column details for a key name value: id: yUheCUmgZ8p key_name: my_column hidden: false description: '' type: integer last_written: '2022-07-26T22:38:05Z' created_at: '2022-07-26T22:38:04Z' updated_at: '2022-07-26T22:38:04Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' /1/columns/{datasetSlug}/{columnId}: parameters: - $ref: '#/components/parameters/datasetSlug' - name: columnId description: Unique identifier (ID) of a column. in: path required: true schema: type: string get: security: - configuration_key: [] summary: Get a Column tags: - Columns operationId: getColumn responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Column' example: id: yUheCUmgZ8p key_name: my_column hidden: false description: '' type: integer last_written: '2022-07-26T22:38:05Z' created_at: '2022-07-26T22:38:04Z' updated_at: '2022-07-26T22:38:04Z' '400': description: Bad Request headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- The id provided in the URL is malformed - we expected a 12-char base58-safe string. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' put: security: - configuration_key: [] summary: Update a Column description: | Update a column tags: - Columns operationId: updateColumn requestBody: content: application/json: schema: $ref: '#/components/schemas/Column' required: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Column' example: id: yUheCUmgZ8p key_name: my_column hidden: false description: '' type: string last_written: '2022-07-26T22:38:05Z' created_at: '2022-07-26T22:38:04Z' updated_at: '2022-07-26T22:38:04Z' '400': description: Bad Request headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Key name cannot be blank '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' delete: security: - configuration_key: [] summary: Delete a Column description: > Delete a column. **Note**: Deleted columns are no longer queryable, but data in existing permalinks (query results and trace views) will remain stored and available at those links. tags: - Columns operationId: deleteColumn responses: '204': description: Success - no content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' /2/teams/{teamSlug}/api-keys: parameters: - $ref: '#/components/parameters/teamSlug' get: security: - bearerAuth: - api-keys:read tags: - Key Management summary: List all API Keys description: | List all API Keys for a Team. operationId: listApiKeys parameters: - $ref: '#/components/parameters/PaginationCursor' - $ref: '#/components/parameters/PaginationSize' - name: filter[type] in: query schema: type: string enum: - configuration - ingest description: > Specifies the type of API key to return. This parameter accepts the following values: - `ingest`: Returns only ingest API keys. - `configuration`: Returns only configuration API keys. The endpoint will default to fetching all API keys regardless of type if this filter is omitted. required: false responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/ApiKeyListResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' post: security: - bearerAuth: - api-keys:write tags: - Key Management summary: Create an API Key description: > This creates an API Key, which will return the API Key components in the response. The Key ID will be found at `data.id` and the Key Secret will be found at `data.attributes.secret`. For security reasons the Key Secret will only be available during creation so make sure to save it. To use a newly-created Ingest Key it should be passed in the `X-Honeycomb-Team` header with the API Key's ID and secret concatenated (and with no separator). For example, `X-Honeycomb-Team: hcxik_1234567890123456789012345612345678901234567890123456789012` Check out our [best practices for API Keys](https://docs.honeycomb.io/get-started/best-practices/api-keys/#ingest-keys). operationId: createApiKey requestBody: required: true content: application/vnd.api+json: schema: $ref: '#/components/schemas/ApiKeyCreateRequest' responses: '201': description: Created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/ApiKeyCreateResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/PayloadTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /2/teams/{teamSlug}/api-keys/{ID}: parameters: - $ref: '#/components/parameters/teamSlug' - $ref: '#/components/parameters/ID' get: security: - bearerAuth: - api-keys:read tags: - Key Management summary: Get an API Key description: > Fetches an environment API Key, either a key of type `ingest` or type `configuration` based on the ID given. operationId: getApiKey responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/ApiKeyResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' patch: security: - bearerAuth: - api-keys:write tags: - Key Management summary: Update an API Key description: > Updates an API Key. The expected attributes depend on the key type: - **Ingest Keys** (prefix `hcxik_`): Support `name` and `enabled` attributes - **Configuration Keys** (prefix `hcxlk_`): Support `name`, `enabled`, and `permissions` attributes operationId: updateApiKey requestBody: required: true content: application/vnd.api+json: schema: $ref: '#/components/schemas/ApiKeyUpdateRequest' examples: ingestKey: summary: Update an Ingest Key value: data: id: hcxik_12345678901234567890123456 type: api-keys attributes: name: updated name disabled: false configurationKey: summary: Update a Configuration Key value: data: id: hcxlk_12345678901234567890123456 type: api-keys attributes: name: updated name disabled: false permissions: create_datasets: true send_events: true manage_markers: true manage_triggers: true manage_boards: true run_queries: true manage_columns: true manage_slos: true manage_recipients: true manage_privateBoards: false read_service_maps: true visible_team_members: true responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/ApiKeyResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/PayloadTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' delete: security: - bearerAuth: - api-keys:write tags: - Key Management summary: Delete an API Key description: > This deletes and immediately deactivates the API Key. This is an irreversible operation. operationId: deleteApiKey responses: '204': description: No Content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /2/teams/{teamSlug}/environments: parameters: - $ref: '#/components/parameters/teamSlug' get: security: - bearerAuth: - environments:read tags: - Environments summary: List all Environments operationId: listEnvironments parameters: - $ref: '#/components/parameters/PaginationCursor' - $ref: '#/components/parameters/PaginationSize' responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/EnvironmentListResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' post: security: - bearerAuth: - environments:write tags: - Environments summary: Create an Environment operationId: createEnvironment requestBody: required: true content: application/vnd.api+json: schema: $ref: '#/components/schemas/CreateEnvironmentRequest' responses: '201': description: Created headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/EnvironmentResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /2/teams/{teamSlug}/environments/{ID}: parameters: - $ref: '#/components/parameters/teamSlug' - $ref: '#/components/parameters/ID' get: security: - bearerAuth: - environments:read tags: - Environments summary: Get an Environment operationId: getEnvironment responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/EnvironmentResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' patch: security: - bearerAuth: - environments:write tags: - Environments summary: Update an Environment operationId: updateEnvironment requestBody: required: true content: application/vnd.api+json: schema: $ref: '#/components/schemas/UpdateEnvironmentRequest' responses: '200': description: Success headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/vnd.api+json: schema: $ref: '#/components/schemas/EnvironmentResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/PayloadTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' delete: security: - bearerAuth: - environments:write tags: - Environments summary: Delete an Environment description: > This deletes and immediately deactivates the Environment. This is an irreversible operation. Environments with Deletion Protection enabled cannot be deleted. To delete an Environment with Deletion Protection enabled, first disable Deletion Protection by updating the Environment with `settings.delete_protected = false`. operationId: deleteEnvironment responses: '204': description: No Content headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: datasetSlug: name: datasetSlug description: | The dataset slug. in: path required: true schema: type: string datasetSlugOrAll: name: datasetSlug description: > The dataset slug or use `__all__` for endpoints that support environment-wide operations. in: path required: true schema: type: string recipientId: name: recipientId description: Unique identifier (ID) of a Recipient. in: path required: true schema: type: string teamSlug: name: teamSlug description: The slug of the Team in: path required: true schema: type: string ID: name: ID description: A unique identifier in: path required: true schema: type: string PaginationCursor: name: page[after] description: > The string value of the `next` attribute from a previous result page. The cursor value must be empty or omitted for the first request of a cursor-paginated query. in: query schema: type: string example: eyxJjcmAVhdGVkX PaginationSize: name: page[size] description: The number of entries to include per response. Maximum value is 100. in: query schema: type: number minimum: 1 maximum: 100 default: 20 example: 10 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 responses: InternalError: description: InternalError content: application/problem+json: schema: $ref: '#/components/schemas/DetailedError' application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: deny-management-apis: description: Team cannot access management APIs. value: error: >- Your team has been denied access to Management APIs, please contact support to be unblocked. application/problem+json: schema: $ref: '#/components/schemas/DetailedError' 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' Conflict: description: Conflict 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: 409 type: https://api.honeycomb.io/problems/conflict title: >- Request could not be completed due to a conflict with the current state of the target resource. error: A resource by that name already exists. application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' PayloadTooLarge: description: The provided request body was over the maximum allowed size. content: application/json: schema: $ref: '#/components/schemas/DetailedError' example: status: 413 type: https://api.honeycomb.io/problems/payload-too-large title: Request body is too large. error: Body size is larger than maximum size of 100000 bytes UnsupportedMediaType: description: The provided request body had an invalid Content-Type. content: application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' 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' UnprocessableEntity: description: Invalid request headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/problem+json: schema: $ref: '#/components/schemas/ValidationError' application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: The provided request body was invalid. headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/problem+json: schema: $ref: '#/components/schemas/DetailedError' examples: DetailedError: value: status: 400 type: https://api.honeycomb.io/problems/unparseable title: The request body could not be parsed. error: invalid gzip data application/json: schema: $ref: '#/components/schemas/Error' examples: GenericError: value: error: invalid Query data application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' examples: JSONAPIError: value: errors: - id: 06dcdd6508ca822f0e7e2bb4121c1f52 code: invalid title: request body could not be parsed detail: invalid gzip data ValidationFailed: description: Validation Failed headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/problem+json: schema: $ref: '#/components/schemas/ValidationError' example: status: 422 type: https://api.honeycomb.io/problems/validation-failed error: The provided input is invalid. title: The provided input is invalid type_detail: - field: type code: invalid description: 'type: must be a valid value' application/json: schema: $ref: '#/components/schemas/Error' application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' GenericError: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' 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. schemas: 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: true status: type: string readOnly: true 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. ValidationError: x-tags: - Errors allOf: - $ref: '#/components/schemas/DetailedError' - type: object properties: status: type: number readOnly: true default: 422 type: type: string readOnly: true default: https://api.honeycomb.io/problems/validation-failed title: type: string readOnly: true default: The provided input is invalid. type_detail: type: array items: type: object properties: field: type: string readOnly: true code: type: string readOnly: true enum: - invalid - missing - incorrect_type - already_exists description: type: string readOnly: true BatchEvent: type: object properties: data: type: object allOf: - $ref: '#/components/schemas/Event' time: type: string description: > Should be in RFC3339 high precision format (for example, YYYY-MM-DDTHH:MM:SS.mmmZ). May be a Unix epoch (seconds since 1970) with second or greater precision (for example, 1452759330927). Optional. If not set, defaults to the time that the API receives the event. samplerate: type: integer description: > An integer representing the denominator in the fraction 1/n when client-side sampling has been applied. Optional. If not set, defaults to `1`, meaning "not sampled". Refer to [Sampling](https://docs.honeycomb.io/manage-data-volume/sample/sampled-data-in-honeycomb/) for more detail. Event: type: object minProperties: 1 maxProperties: 2000 additionalProperties: description: > A collection of key-value properties that represent the Event. Honeycomb supports basic data types for the values of each Event attribute. ### Limits - 2,000 fields per event. The entire event must be less than 1 MB of uncompressed JSON. - String Fields: Each string field has a maximum length of 64KB. - Number Fields: Integers and Floats are both 64-bit. type: - string - number - boolean Auth: type: object required: - id - type - api_key_access - environment - team properties: id: type: string description: Unique identifier (ID) of the API Key. type: type: string enum: - configuration - ingest description: The type of API Key. api_key_access: type: object properties: events: type: boolean default: false markers: type: boolean default: false triggers: type: boolean default: false boards: type: boolean default: false queries: type: boolean default: false columns: type: boolean default: false createDatasets: type: boolean default: false slos: type: boolean default: false recipients: type: boolean default: false privateBoards: type: boolean default: false environment: type: object properties: name: type: string description: >- The name of the Environment. Will be empty for Classic environments. slug: type: string description: >- The slug of the Environment. Will be empty for Classic environments. team: type: object properties: name: type: string slug: type: string BoardType: type: string description: The type of the board. Only flexible boards are supported. enum: - flexible Board: type: object required: - type - name properties: name: type: string description: The name of the Board. minLength: 1 maxLength: 255 example: My Board description: type: string description: A description of the Board. minLength: 0 maxLength: 1024 example: A board created via the API type: $ref: '#/components/schemas/BoardType' links: type: object readOnly: true properties: board_url: type: string example: >- https://ui.honeycomb.io/myteam/environments/myenvironment/board/2NeeaE9bBLd id: type: string readOnly: true description: Unique identifier (ID), returned in response bodies. example: 2NeeaE9bBLd panels: type: array items: $ref: '#/components/schemas/BoardPanel' layout_generation: type: string description: > The layout generation mode for the board. When set to "auto", the board will be automatically laid out based on the panels. When set to "manual", the board will be laid out manually by the user. enum: - auto - manual default: manual writeOnly: true 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 preset_filters: description: > A list of preset filters to apply to the board. For backwards compatibility, if no preset filters are provided, the existing preset filters will be preserved. If an empty array is provided, all preset filters will be deleted. **Note**: Each board is limited to a maximum of 5 preset filters. Attempting to create or update a board with more than 5 preset filters will result in an error. type: array maxItems: 5 items: $ref: '#/components/schemas/PresetFilter' example: - column: app.Service alias: Service PresetFilter: type: object required: - column - alias properties: column: type: string description: Original name of the column to alias. alias: type: string description: The alias of the preset filter. Maximum length is 50 characters. BoardViewFilter: type: object required: - column - operation properties: column: type: string description: The column name to filter on. example: status operation: type: string description: The filter operation. enum: - '=' - '!=' - '>' - '>=' - < - <= - starts-with - does-not-start-with - ends-with - does-not-end-with - exists - does-not-exist - contains - does-not-contain - in - not-in example: '=' value: description: The value to filter by. example: error CreateBoardViewRequest: type: object required: - name - filters properties: name: type: string description: The name of the view. minLength: 1 maxLength: 255 example: My View filters: type: array description: The filters to apply to this view. minItems: 1 items: $ref: '#/components/schemas/BoardViewFilter' UpdateBoardViewRequest: type: object required: - name - filters properties: id: type: string description: Unique identifier for the board view. example: eC_abc123 name: type: string description: The name of the view. minLength: 1 maxLength: 255 example: My View filters: type: array description: The filters to apply to this view. minItems: 1 items: $ref: '#/components/schemas/BoardViewFilter' BoardViewResponse: type: object properties: id: type: string description: Unique identifier for the board view. example: eC_abc123 name: type: string description: The name of the view. example: My View filters: type: array items: $ref: '#/components/schemas/BoardViewFilter' BoardPanel: type: object oneOf: - $ref: '#/components/schemas/QueryPanel' - $ref: '#/components/schemas/SLOPanel' - $ref: '#/components/schemas/TextPanel' discriminator: propertyName: type mapping: query: '#/components/schemas/QueryPanel' slo: '#/components/schemas/SLOPanel' text: '#/components/schemas/TextPanel' BoardPanelPosition: type: object description: > The position of the panel within the layout. When X and Y coordinates are not specified for any of the panels, the layout will be generated automatically. properties: x_coordinate: type: integer description: The x-axis origin point for placing the panel within the layout. minimum: 0 y_coordinate: type: integer description: The y-axis origin point for placing the panel within the layout. minimum: 0 height: type: integer description: >- The height of the panel. When not specified or set to 0, the height of the panel is calculated dynamically based on the panel type. minimum: 0 width: type: integer description: >- The width of the panel. When not specified or set to 0, the width of the panel is calculated dynamically based on the panel type. minimum: 0 QueryPanel: title: Query Panel type: object required: - query_panel - type properties: type: const: query description: The type of the board panel. position: $ref: '#/components/schemas/BoardPanelPosition' query_panel: type: object required: - query_id - query_annotation_id properties: query_id: type: string description: > The ID of the Query to display on the board. The Query must be in the same environment as the board. example: abc1234e query_style: type: string description: How the query should be displayed on the board. enum: - graph - table - combo default: graph query_annotation_id: type: string description: > The ID of a Query Annotation that provides a name and description for the Query. The Query Annotation must apply to the `query_id` or `query` specified. example: e4c24a35 dataset: type: string readOnly: true description: > The dataset name to which the query is scoped. Empty for environment-wide queries. example: My Dataset visualization_settings: $ref: '#/components/schemas/BoardQueryVisualizationSettings' SLOPanel: title: SLO Panel type: object required: - slo_panel - type properties: type: const: slo description: The type of the board panel. position: $ref: '#/components/schemas/BoardPanelPosition' slo_panel: type: object properties: slo_id: type: string description: > The ID of the SLO to display on the board. The SLO must be in the same environment as the board. example: BGfyxhFto TextPanel: title: Text Panel type: object required: - text_panel - type properties: type: const: text description: The type of the board panel. position: $ref: '#/components/schemas/BoardPanelPosition' text_panel: type: object required: - content properties: content: type: string maxLength: 10000 description: > The text content to display on the board panel. This field supports Markdown formatting. example: '# This is a text panel with some content' Threshold: type: object description: > A threshold line to display on a chart, with optional label and styling. Thresholds allow you to visualize important values or boundaries on your charts. required: - value - color - operation - line_style properties: value: type: number description: The numeric value where the threshold line should be displayed format: double example: 100 label: type: string description: Optional label to display for the threshold (max 35 characters) maxLength: 35 example: Critical color: type: string description: Color for the threshold line enum: - red - yellow - blue - green - purple example: red operation: type: string description: | Threshold operation type: "gt" for greater than, "lt" for less than enum: - gt - lt example: gt line_style: type: string description: > Line style for the threshold: "filled-solid" for filled area with solid line, "filled-dotted" for filled area with dotted line, "solid" for solid line only, "dotted" for dotted line only enum: - filled-solid - filled-dotted - solid - dotted example: filled-solid BoardQueryVisualizationSettings: type: object description: > A map of values to control the display settings for the Query on the Board. Unspecified boolean values are assumed to be `false`. Unspecified integers are assumed to be `0`, unspecified arrays are assumed to be null and unspecified strings are assumed to be empty. This is incompatible with the `graph_settings` field. properties: hide_compare: type: boolean default: false hide_hovers: type: boolean default: false hide_markers: type: boolean default: false utc_xaxis: type: boolean default: false overlaid_charts: type: boolean default: false charts: type: array items: type: object properties: chart_index: type: integer default: 0 chart_type: type: string enum: - default - line - stacked - stat - tsbar - cbar - cpie default: default hide_other: type: boolean default: false log_scale: type: boolean default: false omit_missing_values: type: boolean default: false thresholds: type: array description: > Optional threshold lines to display on this chart. Currently limited to at most 5 entries. maxItems: 5 items: $ref: '#/components/schemas/Threshold' ColumnList: type: array items: $ref: '#/components/schemas/Column' CalculatedField: type: object required: - id - alias - expression - created_at - updated_at properties: id: type: string readOnly: true description: Unique identifier (ID), returned in response bodies. alias: type: string description: >- The human-readable name of the Calculated Field (also called Derived Column), as it will be referenced when building queries. minLength: 1 maxLength: 255 expression: type: string description: > The expression to evaluate to construct this Calculated Field's value. (Calculated Field is also called Derived Column.) Refer to the [Calculated Field Reference](https://docs.honeycomb.io/reference/derived-column-formula/). minLength: 1 maxLength: 4095 description: type: string description: >- A human-readable description for the Calculated Field that displays in the UI. default: '' maxLength: 255 created_at: type: string readOnly: true description: ISO8601 formatted time when the field was created. updated_at: type: string readOnly: true description: ISO8601 formatted time when the field was updated. CalculatedFieldList: type: array items: $ref: '#/components/schemas/CalculatedField' CreateColumn: type: object required: - key_name properties: key_name: type: string description: Name of the Column. example: my_column minLength: 1 maxLength: 255 type: type: string default: string enum: - string - float - integer - boolean - histogram description: >- Type of data that the Column will contain. Histogram is in beta and only works in your Metrics dataset. example: integer description: type: string description: Column description. maxLength: 255 example: An integer column hidden: type: boolean default: false description: >- If `true`, the column is excluded from autocomplete and raw data field lists. id: type: string readOnly: true description: Unique identifier (ID), returned in response bodies. last_written: type: string readOnly: true description: >- ISO8601 formatted time the column was last written to (received event data). created_at: type: string readOnly: true description: ISO8601 formatted time the column was created. updated_at: type: string readOnly: true description: ISO8601 formatted time the column was updated. Column: allOf: - $ref: '#/components/schemas/CreateColumn' properties: key_name: readOnly: true DatasetDefinition: type: - 'null' - object required: - name properties: name: type: string description: >- The name of the Column or of the Calculated Field (also called Derived Column) to map to this Dataset Definition Type. An empty string clears the mapping, potentially reverting to a default mapping. minLength: 0 maxLength: 255 column_type: type: string readOnly: true description: >- Optional: `column` for regular columns and `derived_column` for Calculated Fields (also called Derived Columns) when setting Dataset Definitions. Honeycomb does not use this field when updating Dataset definitions. enum: - column - derived_column DatasetDefinitions: type: object description: > Dataset Definitions describe the fields with special meaning in the Dataset. properties: span_id: description: The unique identifier (ID) for each span. allOf: - $ref: '#/components/schemas/DatasetDefinition' trace_id: description: The ID of the trace this span belongs to. allOf: - $ref: '#/components/schemas/DatasetDefinition' parent_id: description: >- The Parent Span ID - The ID of this span's parent span, the call location the current span was called from. allOf: - $ref: '#/components/schemas/DatasetDefinition' name: description: The name of the function or method where the span was created. allOf: - $ref: '#/components/schemas/DatasetDefinition' service_name: description: The name of the instrumented service. allOf: - $ref: '#/components/schemas/DatasetDefinition' duration_ms: description: Span Duration - How much time the span took, in milliseconds. allOf: - $ref: '#/components/schemas/DatasetDefinition' span_kind: description: >- Metadata: Kind - The kind of Span. For example, `client` or `server`. The use of this field to identify Span Events and Links is deprecated. Use the field Metadata: Annotation Type. allOf: - $ref: '#/components/schemas/DatasetDefinition' annotation_type: description: >- Metadata: Annotation Type - The type of span annotation. For example, `span_event` or `link`. This lets Honeycomb visualize this type of event differently in a trace. Do not use this field for other purposes. allOf: - $ref: '#/components/schemas/DatasetDefinition' link_span_id: description: >- Metadata: Link Span ID - Links let you tie traces and spans to one another. The Link Span ID lets you link to a different span (when used with Link Trace ID). allOf: - $ref: '#/components/schemas/DatasetDefinition' link_trace_id: description: >- Metadata: Link Trace ID - Links let you tie traces and spans to one another. The Link Trace Id lets you link to a different trace or a different span in the same trace (when used with Link Span ID). allOf: - $ref: '#/components/schemas/DatasetDefinition' error: description: Use a Boolean or String to indicate error. allOf: - $ref: '#/components/schemas/DatasetDefinition' status: description: Indicates the success, failure, or other status of a request. allOf: - $ref: '#/components/schemas/DatasetDefinition' route: description: The HTTP URL or equivalent route processed by the request. allOf: - $ref: '#/components/schemas/DatasetDefinition' user: description: The user making the request in the system. allOf: - $ref: '#/components/schemas/DatasetDefinition' log_severity: description: >- Severity level of the event (also known as log level). Supported values: trace, debug, info, warn, error, fatal, unspecified. allOf: - $ref: '#/components/schemas/DatasetDefinition' log_message: description: >- A value containing the log event message. Can be a human-readable string message (including multi-line) describing the event in a free form. allOf: - $ref: '#/components/schemas/DatasetDefinition' Dataset: type: object description: > Datasets are a collection of events from a specific source or related source. required: - name properties: name: type: string description: The name of the dataset. example: My Dataset! minLength: 1 maxLength: 255 description: type: string default: '' description: A description for the dataset. example: A nice description of my dataset minLength: 0 maxLength: 1024 settings: type: object properties: delete_protected: type: boolean description: If true, the dataset cannot be deleted. expand_json_depth: type: integer description: The maximum unpacking depth of nested JSON fields. example: 3 default: 0 minimum: 0 maximum: 10 slug: type: string example: my-dataset- description: The 'slug' of the dataset to be used in URLs. readOnly: true regular_columns_count: type: - 'null' - integer description: > The total number of unique fields for this Dataset. The value will be null if the dataset does not contain any fields yet. example: 100 readOnly: true last_written_at: type: - 'null' - string description: > The ISO8601-formatted time when the dataset last received event data. The value will be null if no data has been received yet. example: '2022-07-21T18:39:23Z' readOnly: true created_at: type: string description: The ISO8601-formatted time when the dataset was created. example: '2022-09-22T17:32:11Z' readOnly: true dataset_type: type: string description: > The type of data contained in the dataset. Only present for time-series metrics datasets. enum: - metrics example: metrics readOnly: true DatasetCreationPayload: type: object description: an object to send to the Dataset API via PUT required: - name properties: name: type: string description: The name of the dataset. minLength: 1 maxLength: 255 description: type: string default: '' description: A description for the dataset. example: A nice description of my dataset minLength: 0 maxLength: 1024 expand_json_depth: type: integer description: The maximum unpacking depth of nested JSON fields. example: 3 default: 0 minimum: 0 maximum: 10 DatasetUpdatePayload: type: object description: an object to send to the Dataset API via PUT required: - description - expand_json_depth properties: description: type: string default: '' description: A description for the dataset. example: A nice description of my dataset minLength: 0 maxLength: 1024 expand_json_depth: type: integer description: The maximum unpacking depth of nested JSON fields. example: 3 default: 0 minimum: 0 maximum: 10 settings: type: object properties: delete_protected: type: boolean description: If true, the dataset cannot be deleted. KinesisEvent: type: object properties: requestId: type: string timestamp: type: integer records: type: array items: $ref: '#/components/schemas/KinesisEventRecord' KinesisEventRecord: type: object properties: data: type: string description: Base64 encoded Kinesis record from AWS KinesisResponse: type: object properties: requestId: type: string timestamp: type: integer errorMessage: type: string Marker: type: object properties: start_time: type: integer description: >- Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives. Expressed in Unix Time. example: 1471040808 end_time: type: integer description: >- Specifies end time, and allows a Marker to be recorded as representing a time range, such as a 5 minute deploy. Expressed in Unix Time. example: 1668453920 message: type: string description: A message to describe this specific Marker. example: 'backend deploy #123' type: type: string description: >- Groups similar Markers. For example, `deploys`. All Markers of the same type appear with the same color on the graph. Refer to the [Marker Settings](/api/marker-settings/) API for altering the color of each type. example: deploy url: type: string description: >- A target for the marker. Clicking the marker text will take you to this URL. example: http://link-to-build.here id: type: string description: A 6 character hexadecimal string assigned on Marker creation. readOnly: true created_at: type: string description: The ISO8601-formatted time when the Marker was created. readOnly: true updated_at: type: string description: The ISO8601-formatted time when the Marker was updated. readOnly: true color: type: string description: >- Color can be assigned to Markers using the Marker Settings endpoint. This field will be populated when List All Markers is called. readOnly: true MarkerSetting: type: object required: - type - color properties: type: type: string description: > Groups similar Markers. For example, 'deploys'. All Markers of the same type appears with the same color on the graph. example: deploy color: type: string description: > Color to use for display of this marker type. Specified as hexadecimal RGB. For example, "#F96E11". example: '#7b1fa2' id: type: string description: The unique identifier (ID) for the Marker Setting. readOnly: true example: gwAHiE5TS4j created_at: type: string description: The ISO8601-formatted time when the Marker Setting was created. readOnly: true example: '2022-09-15T05:39:42Z' updated_at: type: - 'null' - string description: The ISO8601-formatted time when the Marker Setting was updated. readOnly: true example: '2022-12-15T04:25:14Z' 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' 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 muted: type: boolean description: > When `true`, the Recipient is muted for this alert and will not receive notifications. Only applies to Recipients assigned to a Signal via the Anomaly Detection API. FilterOp: type: string enum: - '=' - '!=' - '>' - '>=' - < - <= - starts-with - does-not-start-with - ends-with - does-not-end-with - exists - does-not-exist - contains - does-not-contain - in - not-in FilterColumn: type: - 'null' - string FilterValue: anyOf: - type: 'null' - type: integer - type: number - type: string - type: boolean - type: array FilterCombination: type: string default: AND enum: - AND - OR description: Set to "OR" to match ANY filter in the filter list HavingOp: type: string enum: - '=' - '!=' - '>' - '>=' - < - <= HavingCalculateOp: type: string enum: - COUNT - CONCURRENCY - SUM - AVG - COUNT_DISTINCT - MAX - MIN - P001 - P01 - P05 - P10 - P20 - P25 - P50 - P75 - P80 - P90 - P95 - P99 - P999 - RATE_AVG - RATE_SUM - RATE_MAX QueryOp: type: string enum: - COUNT - CONCURRENCY - SUM - AVG - COUNT_DISTINCT - HEATMAP - MAX - MIN - P001 - P01 - P05 - P10 - P20 - P25 - P50 - P75 - P80 - P90 - P95 - P99 - P999 - RATE_AVG - RATE_SUM - RATE_MAX Query: type: object properties: id: type: string readOnly: true breakdowns: type: array default: - user_agent maxItems: 100 items: type: string description: the columns by which to break events down into groups calculations: type: array description: the calculations to return as a time series and summary table maxItems: 100 items: type: object required: - op properties: op: allOf: - $ref: '#/components/schemas/QueryOp' - default: COUNT column: type: - 'null' - string description: The name of the column name: type: - 'null' - string description: >- The name of the calculation. This is required if using calculation filters. Only available in Metrics Beta. filters: type: array maxItems: 100 items: type: object required: - column - op properties: op: $ref: '#/components/schemas/FilterOp' column: $ref: '#/components/schemas/FilterColumn' value: $ref: '#/components/schemas/FilterValue' description: >- The filters with which to restrict the results of this particular calculation. Does not support relational fields. Only available in Metrics Beta. filter_combination: $ref: '#/components/schemas/FilterCombination' filters: type: array maxItems: 100 items: type: object required: - column - op properties: op: $ref: '#/components/schemas/FilterOp' column: $ref: '#/components/schemas/FilterColumn' value: $ref: '#/components/schemas/FilterValue' description: The filters with which to restrict the considered events filter_combination: $ref: '#/components/schemas/FilterCombination' formulas: type: array description: >- Mathematical formulas to be returned as a time series and summary table. Formulas operate on the results of calculations and are returned in query results instead of calculations. Only available in Metrics Beta. maxItems: 100 items: type: object required: - name - expression properties: name: type: - string description: The name of the formula expression: type: - string description: >- An expression that follows the same syntax as calculated field expressions, but uses the names of items in the calculations list in place of column names. granularity: type: integer minimum: 1 description: > The time resolution of the query's graph, in seconds. Given a query time range T, valid values (T/1000...T/1). If left blank, granularity may be set to a sub-second value for queries with short time ranges. orders: type: array maxItems: 100 items: type: object properties: column: type: string op: $ref: '#/components/schemas/QueryOp' order: type: string default: ascending enum: - ascending - descending description: > The terms on which to order the query results. Each term must appear in the `breakdowns` field, the `calculations` field, or the `formulas` field. Formulas and calculations with name properties can be referenced by putting the name in the column property. limit: type: integer default: 100 minimum: 1 maximum: 10000 description: > The maximum number of unique groups returned in 'results'. Aggregating many unique groups across a large time range is computationally expensive, and too high a limit with too many unique groups may cause queries to fail completely. Limiting the results to only the needed values can significantly speed up queries. The normal allowed maximum value when creating a query is 1_000. When running 'disable_series' queries, this can be overridden to be up to 10_000, so the maximum value returned from the API when fetching a query may be up to 10_000. start_time: type: integer minimum: 1 default: 1676399428 description: > Absolute start time of query, in seconds since UNIX epoch. Must be <= `end_time`. end_time: type: integer minimum: 1 default: 1676467828 description: Absolute end time of query, in seconds since UNIX epoch. time_range: type: integer minimum: 1 default: 7200 description: > Time range of query in seconds. Can be used with either `start_time` (seconds after `start_time`), `end_time` (seconds before `end_time`), or without either (seconds before now). havings: type: array description: > The Having clause allows you to filter on the results table. This operation is distinct from the Where clause, which filters the underlying events. Order By allows you to order the results, and Having filters them. Formulas and calculations with name properties can be referenced by putting the name in the column property. maxItems: 100 items: type: object required: - calculate_op properties: calculate_op: allOf: - $ref: '#/components/schemas/HavingCalculateOp' column: type: - 'null' - string description: >- The name of the column to filter against. This can also be a calculation or formula name. op: allOf: - $ref: '#/components/schemas/HavingOp' value: type: number default: 10 calculated_fields: type: array description: | Computed properties that are calculated by a formula. maxItems: 100 items: type: object required: - name - expression properties: name: type: string description: The field name expression: type: string description: >- The formula for your Calculated Field. To learn more about syntax and available functions, and to explore some example formulas, visit [Calculated Field Formula Reference](https://docs.honeycomb.io/reference/derived-column-formula/). compare_time_offset_seconds: type: integer enum: - 1800 - 3600 - 7200 - 28800 - 86400 - 604800 - 2419200 - 15724800 description: > When set, offsets the query's time range by this number of seconds into the past, allowing comparison with historical data from an earlier time period. For example, setting this to 86400 (24 hours) will compare current results against data from 24 hours ago. ##### Note - The offset must be greater than or equal to the query's time range duration. ##### Allowed values - same time range as query time range - `1800` - 30 minutes - `3600` - 1 hour - `7200` - 2 hours - `28800` - 8 hours - `86400` - 24 hours - `604800` - 7 days - `2419200` - 28 days - `15724800` - 6 months usage_mode: type: boolean description: > If `true`, query results will return aggregates without correcting for sample rates. This is useful for understanding the actual volume of data stored rather than the estimated original event counts. By default, aggregates are adjusted to reflect the estimated original event volume based on sample rates. Note: This field is not supported for triggers. default: false QueryAnnotation: type: object description: >- A Query Annotation consists of a name and description associated with a query to add context when collaborating. required: - name - query_id properties: name: type: string description: A name for the Query. example: My Named Query minLength: 1 maxLength: 320 description: type: string description: A description of the Query. example: A nice description of My Named Query maxLength: 1023 query_id: type: string description: > The ID of the Query that the annotation describes. **Note**: Once created, it is NOT possible to change the query ID associated with an annotation. It is possible to have multiple annotations associated with a Query. example: mabAMpSPDjH id: type: string description: The unique identifier (ID) of a Query Annotation. readOnly: true example: sGUnkBHgRFN created_at: type: string format: date-time description: ISO8601 formatted time when the Query Annotation was created. example: '2022-10-26T21:36:04Z' readOnly: true updated_at: type: string format: date-time description: ISO8601 formatted time when the Query Annotation was updated. example: '2022-12-04T08:14:26Z' readOnly: true source: type: string description: The source of the Query Annotation. example: query enum: - query - board readOnly: true CreateQueryResultRequest: type: object description: A Query Result is created with the Query ID. required: - query_id properties: query_id: type: string writeOnly: true description: > The ID of a query returned from the [Queries endpoint](/api/queries/). example: mabAMpSPDjH disable_series: type: boolean writeOnly: true description: > If `true`, timeseries data will not be returned in the `series` response field, and only summarized data will be returned in the `results` response field. default: false disable_total_by_aggregate: type: boolean writeOnly: true description: > If `true`, data representing each aggregate in the query's total value will not be returned. Ensure `disable_series` is false to return the timeseries data. default: true disable_other_by_aggregate: type: boolean default: true writeOnly: true description: > If true, the "other_by_aggregate" data is excluded from the query result. limit: type: integer writeOnly: true maximum: 10000 description: > If `disable_series` is `true`, a limit may be optionally given. The limit will override the default limit of 1_000 results with a maximum available limit of 10_000. If `disable_series` is `false`, this field will be ignored. QueryResult: type: object description: A Query Result is created with the Query ID. properties: query: readOnly: true allOf: - $ref: '#/components/schemas/Query' id: type: string description: The unique identifier (ID) of a Query Result. readOnly: true example: sGUnkBHgRFN complete: type: boolean description: >- Indicates if the query results are available yet or not. For example, is the query still being processed or complete? readOnly: true example: false links: type: object description: >- An object containing UI links to the query result and query result graph readOnly: true properties: query_url: type: string example: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/HprJhV1fYy graph_image_url: type: string example: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/HprJhV1fYy/snapshot QueryResultsData: type: object description: Query result details properties: data: type: object examples: - COUNT: 1 P99(duration_ms): 210 name: TestGoogleCallbackLogin test.classname: github.com/honeycombio/hound/cmd/poodle/handlers test.status: passed - COUNT: 77481 P99(duration_ms): 857.0309715273646 name: TestGoogleCallbackLogin test.classname: github.com/honeycombio/hound/cmd/poodle/handlers test.status: passed - FormulaName: 0.85 test.status: passed - CalculationName: 77481 test.status: passed additionalProperties: type: - string - boolean - number QueryResultsSeries: type: object allOf: - $ref: '#/components/schemas/QueryResultsData' properties: time: type: string example: '2021-04-09T14:16:00Z' QueryResultDetails: type: object description: > Query Results for the Query ID. The response body will be a JSON object with "complete": true and the results populated once the query is complete. If the query fails to run, the response will still return HTTP 200 with "complete": true, but the "data" field will be replaced by an "error" field describing the failure. The response body will contain caching headers to indicate that once complete, and the Query Result may be cached, as it will not change. properties: query: readOnly: true allOf: - $ref: '#/components/schemas/Query' id: type: string description: The unique identifier (ID) of a Query Result readOnly: true example: sGUnkBHgRFN complete: type: boolean description: >- Indicates if the query results are available yet or not. For example, is the query still being processed or complete? readOnly: true example: true error: type: string description: > Only present if the query failed to run. Contains a human-readable message describing the failure. When set, the "data" field is omitted. readOnly: true example: we had trouble fetching your results! try again? data: type: object description: An object containing the query result data properties: series: type: array description: >- Timeseries data from the query result (equivalent to the graph data in the Honeycomb UI) items: $ref: '#/components/schemas/QueryResultsSeries' results: type: array description: >- Query results data (equivalent to the Overview in the Honeycomb UI below the graph) items: $ref: '#/components/schemas/QueryResultsData' total_by_aggregate: $ref: '#/components/schemas/QueryResultsData' description: > An object containing each aggregate in the query mapped to its total value across all groups. Aggregate values do not respect any Having clauses included in a query. Only available if query was run with `disable_total_by_aggregate` set to `false`. total_by_aggregate_series: type: array description: > Timeseries data showing the total value of each aggregate returned in `total_by_aggregate` across the time range. Aggregate values returned do not respect any Having clauses included in a query. Only available if both `disable_total_by_aggregate` and `disable_series` are set to `false`. items: $ref: '#/components/schemas/QueryResultsSeries' other_by_aggregate: $ref: '#/components/schemas/QueryResultsData' description: > An object containing each aggregate in the query mapped to its value for the groups not included in the query limit. Aggregate values do not respect any Having clauses included in a query. Only available if query was run with `disable_other_by_aggregate` set to `false`. links: type: object description: >- An object containing UI links to the query result and query result graph properties: query_url: type: string description: A link to the query result in the Honeycomb UI example: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/HprJhV1fYy graph_image_url: type: string description: A direct link to the graph image from the query result example: >- https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/HprJhV1fYy/snapshot RecipientType: type: string description: One of the supported Recipient Types enum: - pagerduty - email - slack - webhook - msteams - msteams_workflow PagerDutyRecipient: allOf: - $ref: '#/components/schemas/RecipientProperties' - type: object properties: type: type: string enum: - pagerduty - type: object properties: details: type: object required: - pagerduty_integration_name - pagerduty_integration_key description: Specific schema for the Pagerduty Recipient Type properties: pagerduty_integration_name: type: string description: A name for this Integration. example: Example PagerDuty Service pagerduty_integration_key: type: string description: Pagerduty Integration Key. example: 7zOwh1edS8xHGcwfb2bA4sqY8E6PJzSK minLength: 32 maxLength: 32 EmailRecipient: allOf: - $ref: '#/components/schemas/RecipientProperties' - type: object properties: type: type: string enum: - email - type: object properties: details: type: object required: - email_address description: Specific schema for the Email Recipient Type properties: email_address: type: string description: Email address to notify. example: notify-me@example-email.com SlackRecipient: allOf: - $ref: '#/components/schemas/RecipientProperties' - type: object properties: type: type: string enum: - slack - type: object properties: details: type: object required: - slack_channel description: Specific schema for the Slack Recipient Type. properties: slack_channel: type: string description: Slack channel to notify. example: '#alerts-channel' MSTeamsRecipient: allOf: - $ref: '#/components/schemas/RecipientProperties' - type: object properties: type: type: string enum: - msteams - type: object deprecated: true properties: details: type: object required: - webhook_name - webhook_url description: >- Specific schema for the MS Teams Recipient Type. Now deprecated, please use the `msteams_workflow` type instead. properties: webhook_name: type: string description: A name for this recipient. example: My Teams Channel webhook_url: type: string description: Incoming webhook URL of an Teams instance. example: https://yourco.webhook.office.com/webhook/xxxx MSTeamsWorkflowRecipient: allOf: - $ref: '#/components/schemas/RecipientProperties' - type: object properties: type: type: string enum: - msteams_workflow - type: object properties: details: type: object required: - webhook_name - webhook_url description: Specific schema for the MS Teams Workflow Recipient Type. properties: webhook_name: type: string maxLength: 255 description: A name for this recipient. example: My Teams Channel webhook_url: type: string maxLength: 2048 description: Incoming webhook URL of an Teams instance. example: >- https://test-123.westus.logic.azure.com:443/workflows/54321/triggers/manual/paths/invoke WebhookRecipient: allOf: - $ref: '#/components/schemas/RecipientProperties' - type: object properties: type: type: string enum: - webhook - type: object properties: details: type: object required: - webhook_name - webhook_url description: Specific schema for the Webhook Recipient Type properties: webhook_headers: type: array maxItems: 5 description: Custom headers for this webhook items: $ref: '#/components/schemas/WebhookHeader' example: - header: Authorization value: Bearer xyz123 webhook_name: type: string maxLength: 255 description: A name for this Integration. example: Example webhook webhook_url: type: string description: Webhook URL. maxLength: 2048 example: https://webhook.example.com webhook_secret: type: string description: Webhook secret. maxLength: 255 example: secret webhook_payloads: type: object description: Specify a custom webhook payload. properties: template_variables: type: array maxItems: 10 description: Custom variable definitions for this webhook items: $ref: '#/components/schemas/TemplateVariableDefinition' example: - name: severity default_value: CRITICAL payload_templates: type: object properties: trigger: $ref: '#/components/schemas/PayloadTemplate' budget_rate: $ref: '#/components/schemas/PayloadTemplate' exhaustion_time: $ref: '#/components/schemas/PayloadTemplate' WebhookHeader: type: object required: - header properties: header: type: string maxLength: 64 value: type: string maxLength: 750 TemplateVariableDefinition: type: object required: - name properties: name: type: string pattern: ^[a-z](?:[a-zA-Z0-9]+$)?$ maxLength: 64 example: severity default_value: type: string maxLength: 256 example: CRITICAL PayloadTemplate: type: object properties: body: type: string example: '{ \"alert\": \"{{.Alert.Description}}\" }' Recipient: type: object required: - type properties: type: type: string discriminator: propertyName: type mapping: pagerduty: '#/components/schemas/PagerDutyRecipient' email: '#/components/schemas/EmailRecipient' slack: '#/components/schemas/SlackRecipient' webhook: '#/components/schemas/WebhookRecipient' msteams: '#/components/schemas/MSTeamsRecipient' msteams_workflow: '#/components/schemas/MSTeamsWorkflowRecipient' oneOf: - $ref: '#/components/schemas/PagerDutyRecipient' - $ref: '#/components/schemas/EmailRecipient' - $ref: '#/components/schemas/SlackRecipient' - $ref: '#/components/schemas/WebhookRecipient' - $ref: '#/components/schemas/MSTeamsRecipient' - $ref: '#/components/schemas/MSTeamsWorkflowRecipient' RecipientProperties: type: object properties: id: type: string readOnly: true example: yUheCUmgZ8p created_at: type: string format: date-time description: ISO8601 formatted time the Recipient was created. example: '2022-07-26T22:38:04Z' readOnly: true updated_at: type: string format: date-time description: ISO8601 formatted time the Recipient was updated. example: '2022-07-26T22:38:04Z' readOnly: true type: $ref: '#/components/schemas/RecipientType' 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 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: {} auto_investigate: x-internal: true type: boolean description: > When true, Honeycomb will automatically start an investigation when this Trigger fires. default: false example: false 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/). CreateTriggerRequest: oneOf: - $ref: '#/components/schemas/TriggerWithInlineQuery' - $ref: '#/components/schemas/TriggerWithQueryReference' TriggerResponse: allOf: - $ref: '#/components/schemas/TriggerWithInlineQuery' - $ref: '#/components/schemas/TriggerWithQueryReference' SLOCreate: type: object required: - name - time_period_days - target_per_million - sli properties: id: type: string readOnly: true name: type: string description: The name of the SLO. minLength: 1 maxLength: 120 example: My SLO description: type: string description: A nice description of the SLO's intent and context. minLength: 0 maxLength: 1023 example: SLO to ensure requests succeed and are fast sli: type: object description: >- Reference to the [Calculated Field (also called Derived Column)](/api/calculated-fields/) used as the indicator of event success. required: - alias properties: alias: type: string description: The alias of the Calculated Field (also called Derived Column). minLength: 1 maxLength: 255 example: alias: error_sli time_period_days: type: integer description: The time period, in days, over which the SLO will be evaluated. minimum: 1 example: 30 target_per_million: type: integer description: >- The number of events out of one million (1,000,000) that you expected qualified events to succeed. minimum: 0 maximum: 999999 example: 990000 tags: type: array description: A list of key-value pairs to help identify the SLO. maxItems: 10 items: $ref: '#/components/schemas/Tag' example: - key: team value: blue reset_at: type: - 'null' - string format: date-time description: >- The ISO8601-formatted time the SLO was last reset. The value will be `null` if the SLO has not yet been reset. readOnly: true example: 2022-011-11T09:53:04Z created_at: type: string description: The ISO8601-formatted time when the SLO was created. format: date-time readOnly: true example: '2022-09-22T17:32:11Z' updated_at: type: string format: date-time description: The ISO8601-formatted time when the SLO was updated. readOnly: true example: '2022-10-31T15:08:11Z' dataset_slugs: type: array description: >- The dataset(s) the SLO will be evaluated against. Required if using `__all__` in the path. minItems: 1 maxItems: 10 example: - mydataset1 - mydataset2 SLO: type: object required: - name - time_period_days - target_per_million - sli properties: id: type: string readOnly: true name: type: string description: The name of the SLO. minLength: 1 maxLength: 120 example: My SLO description: type: string description: A nice description of the SLO's intent and context. minLength: 0 maxLength: 1023 example: SLO to ensure requests succeed and are fast sli: type: object description: >- Reference to the [Calculated Field](/api/calculated-fields/) used as the indicator of event success. required: - alias properties: alias: type: string description: The alias of the Calculated Field (also called Derived Column). minLength: 1 maxLength: 255 example: alias: error_sli time_period_days: type: integer description: The time period, in days, over which the SLO will be evaluated. minimum: 1 example: 30 target_per_million: type: integer description: >- The number of events out of one million (1,000,000) that you expected qualified events to succeed. minimum: 0 maximum: 999999 example: 990000 tags: type: array description: A list of key-value pairs to help identify the SLO. maxItems: 10 items: $ref: '#/components/schemas/Tag' example: - key: team value: blue reset_at: type: - 'null' - string format: date-time description: >- The ISO8601-formatted time the SLO was last reset. The value will be `null` if the SLO has not yet been reset. readOnly: true example: 2022-011-11T09:53:04Z created_at: type: string description: The ISO8601-formatted time when the SLO was created. format: date-time readOnly: true example: '2022-09-22T17:32:11Z' updated_at: type: string format: date-time description: The ISO8601-formatted time when the SLO was updated. readOnly: true example: '2022-10-31T15:08:11Z' dataset_slugs: type: array description: >- The dataset(s) the SLO will be evaluated against. Required if using `__all__` in the path. readOnly: true minItems: 1 maxItems: 10 example: - mydataset1 - mydataset2 SLODetailedResponse: allOf: - $ref: '#/components/schemas/SLO' type: object properties: compliance: type: number description: > Reporting data to express historical compliance of the SLO. Only included when the `?detailed` query param is passed. format: double readOnly: true example: 95.39 budget_remaining: type: number description: > Reporting data to express how much error budget remains for the time period of the SLO. Only included when the `?detailed` query param is passed. format: double readOnly: true example: 7.73 status: type: string description: | Reporting data to express the status of the SLO. Status can be one of the following: - `normal` : The SLO has no burn alerts triggered. - `triggered`: The SLO has at least one burn alert triggered. - `no_alerts`: The SLO has no burn alerts associated with it. - `no_events`: The SLO has no events streaming in. Only included when the `?detailed` query param is passed. enum: - normal - triggered - no_alerts - no_events readOnly: true example: normal burn_rate: type: number description: | Reporting data to express the ratio of actual failures in the SLO to expected failures in the given time window. The time window defaults to 4 hours for the API response. Only included when the `?detailed` query param is passed. format: double readOnly: true example: 5.39 SLOHistoryRequest: type: object required: - ids - start_time - end_time properties: ids: type: array description: > A list of SLO IDs to retrieve history for. Cannot be an empty array or more than 24 in length. minItems: 1 maxItems: 24 example: - 2LBq9LckbcA - CzcpPs7cJ4d start_time: type: integer description: >- The starting Unix timestamp, in seconds since the epoch, to retrieve historical data for. Cannot be more than a year in the past. example: 1742230800 end_time: type: integer description: >- The ending Unix timestamp, in seconds since the epoch, to retrieve historical data for. Must be greater than `start_time`. Cannot be a future timestamp. example: 1745254800 SLOHistoryResponse: type: object description: > A mapping from SLO IDs (e.g., "2LBq9LckbcA") to their historical data. Each SLO ID maps to an array of compliance and budget intervals. additionalProperties: type: array items: $ref: '#/components/schemas/SLOHistory' example: 2LBq9LckbcA: - timestamp: 1744650000 compliance: 91.44851657940663 budget_remaining: 14.48516579406632 - timestamp: 1744653600 compliance: 97.98746514671242 budget_remaining: 88.13453467953423 CzcpPs7cJ4d: - timestamp: 1744650000 compliance: 93.53414567784128 budget_remaining: -71.02966841186735 SLOHistory: type: object properties: timestamp: type: integer description: >- The starting Unix timestamp, in seconds since the epoch, for the interval. readOnly: true example: 1744650000 compliance: type: number description: | Historical compliance of the SLO in this interval. format: double readOnly: true example: 91.44851657940663 budget_remaining: type: number description: | How much error budget remains for the SLO in this interval. format: double readOnly: true example: 14.48516579406632 SLOCountsResponse: type: object properties: slo_id: type: string description: The unique identifier of the SLO. readOnly: true example: bZ1aRHAUsjG resolution_seconds: type: integer description: The width of each window in seconds. Always `60`. readOnly: true example: 60 epoch: type: string description: > A hash of the SLO's SLI expression and dataset configuration. This value changes whenever the SLO definition changes in a way that affects count computation (e.g. a derived column expression update). Clients should compare this value across responses: a change means counts have reset under a new key and any client-side cache should be invalidated. readOnly: true example: a3f9c2d1e8b74056 period_start: type: integer format: int64 description: > Unix timestamp of the start of the current accumulation period (the most recent hour boundary). The cumulative totals used to compute deltas reset to zero at this point. Clients should re-baseline their delta computations whenever this value changes between responses. readOnly: true example: 1745251200 windows: type: array description: > Ordered list of per-minute count windows within the requested time range. Gaps between windows indicate minutes with no recorded snapshot. An empty array means no data exists for the requested range. items: $ref: '#/components/schemas/SLOCountWindow' SLOCountWindow: type: object properties: window_start: type: integer description: Start of the window as a Unix timestamp (seconds). readOnly: true example: 1745251200 window_end: type: integer description: > End of the window as a Unix timestamp (seconds). Always `window_start + 60`. readOnly: true example: 1745254260 total_count: type: integer description: Total number of events (good + bad) in this window. readOnly: true example: 1243 error_count: type: integer description: Number of failed (bad) events in this window. readOnly: true example: 3 is_partial: type: boolean description: > When `true`, the data for this window may be incomplete. This occurs in three cases: 1. **No prior anchor**: The first window has no preceding snapshot to delta from, so the value is a raw cumulative total rather than a true per-minute delta. 2. **Settlement window**: The window started within the last 10 minutes. Late-arriving events from client buffering or ingestion lag may still appear in a subsequent snapshot. 3. **Hour boundary reset**: Cumulative totals reset to zero at each hour boundary. A request spanning a boundary will see the new hour's counts start near zero while the anchor came from the prior hour's larger total. Both `total_count` and `error_count` are zeroed for this window. Use `period_start` to detect this and avoid requesting ranges that cross a boundary. Clients building alerting on top of this data should treat `is_partial: true` windows as provisional. readOnly: true example: false SLOHourlyCountsResponse: type: object properties: slo_id: type: string description: The unique identifier of the SLO. readOnly: true example: bZ1aRHAUsjG resolution_seconds: type: integer description: The width of each bucket in seconds. Always `3600`. readOnly: true example: 3600 buckets: type: array description: > Ordered list of hourly count buckets within the requested time range. Gaps indicate hours with no recorded data. An empty array means no data exists for the requested range. items: $ref: '#/components/schemas/SLOHourBucket' SLOHourBucket: type: object properties: start_time: type: integer format: int64 description: Start of the hour as a Unix timestamp (seconds). readOnly: true example: 1745168400 end_time: type: integer format: int64 description: > End of the hour as a Unix timestamp (seconds). Always `start_time + 3600`. readOnly: true example: 1745172000 total_count: type: integer description: Total number of events (good + bad) in this hour. readOnly: true example: 74520 error_count: type: integer description: Number of failed (bad) events in this hour. readOnly: true example: 182 is_partial: type: boolean description: > When `true`, this bucket covers the current in-progress hour and its counts will increase until the hour completes. Clients should treat `is_partial: true` buckets as provisional. readOnly: true example: false BurnAlertListResponse: type: object required: - alert_type properties: alert_type: type: string oneOf: - $ref: '#/components/schemas/ExhaustionTimeBurnAlertListResponse' - $ref: '#/components/schemas/BudgetRateBurnAlertListResponse' discriminator: propertyName: alert_type mapping: exhaustion_time: '#/components/schemas/ExhaustionTimeBurnAlertListResponse' budget_rate: '#/components/schemas/BudgetRateBurnAlertListResponse' BurnAlertDetailResponse: type: object required: - alert_type properties: alert_type: type: string oneOf: - $ref: '#/components/schemas/ExhaustionTimeBurnAlertDetailResponse' - $ref: '#/components/schemas/BudgetRateBurnAlertDetailResponse' discriminator: propertyName: alert_type mapping: exhaustion_time: '#/components/schemas/ExhaustionTimeBurnAlertDetailResponse' budget_rate: '#/components/schemas/BudgetRateBurnAlertDetailResponse' CreateBurnAlertRequest: type: object required: - alert_type properties: alert_type: type: string oneOf: - $ref: '#/components/schemas/CreateExhaustionTimeBurnAlertRequest' - $ref: '#/components/schemas/CreateBudgetRateBurnAlertRequest' discriminator: propertyName: alert_type mapping: exhaustion_time: '#/components/schemas/CreateExhaustionTimeBurnAlertRequest' budget_rate: '#/components/schemas/CreateBudgetRateBurnAlertRequest' UpdateBurnAlertRequest: type: object required: - alert_type properties: alert_type: type: string oneOf: - $ref: '#/components/schemas/UpdateExhaustionTimeBurnAlertRequest' - $ref: '#/components/schemas/UpdateBudgetRateBurnAlertRequest' discriminator: propertyName: alert_type mapping: exhaustion_time: '#/components/schemas/UpdateExhaustionTimeBurnAlertRequest' budget_rate: '#/components/schemas/UpdateBudgetRateBurnAlertRequest' BurnAlertSharedParams: type: object properties: id: type: string description: Unique identifier (ID) of a Burn alert. readOnly: true example: fS7vfB81Wcy description: type: string description: A description of the Burn Alert. maxLength: 1023 example: Use this runbook if this alert fires. triggered: type: boolean description: > Indicates if the Burn Alert has been triggered. This field is read-only and is set to `true` when the alert is triggered. readOnly: true example: false created_at: type: string format: date-time description: The ISO8601-formatted time when the Burn Alert was created. readOnly: true example: '2022-09-22T17:32:11Z' updated_at: type: string format: date-time description: The ISO8601-formatted time when the Burn Alert was updated. readOnly: true example: '2022-10-31T15:08:11Z' auto_investigate: x-internal: true type: boolean description: > When true, Honeycomb will automatically start an investigation when this Burn Alert fires. default: false example: false ExhaustionTimeBurnAlert: title: Exhaustion Time allOf: - $ref: '#/components/schemas/BurnAlertSharedParams' - type: object required: - exhaustion_minutes properties: alert_type: type: string description: > One of the supported alert types: 1. `exhaustion_time`: Notifies when you are about to run out of SLO budget within a specified number of hours. 1. `budget_rate`: Notifies when budget drops by at least a specified percentage within a defined time window. default: exhaustion_time enum: - exhaustion_time - budget_rate example: exhaustion_time exhaustion_minutes: type: integer minimum: 0 description: > Required when `alert_type` is `exhaustion_time`. Must not be specified when `alert_type` is `budget_rate`. Amount of time (in minutes) left until your projected SLO budget is exhausted. The alert will fire when this exhaustion threshold is reached. example: 120 ExhaustionTimeBurnAlertListResponse: allOf: - $ref: '#/components/schemas/ExhaustionTimeBurnAlert' - type: object properties: slo: type: object description: Details about the SLO associated with the burn alert. properties: id: type: string description: Unique identifier (ID) of a SLO. example: id: 2LBq9LckbcA ExhaustionTimeBurnAlertDetailResponse: title: Exhaustion Time allOf: - $ref: '#/components/schemas/ExhaustionTimeBurnAlertListResponse' - type: object properties: recipients: type: array minItems: 1 description: > A list of [Recipients](/api/recipients/) to notify when an alert fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID. items: $ref: '#/components/schemas/NotificationRecipient' example: - id: abcd123 type: email target: alerts@example.com CreateExhaustionTimeBurnAlertRequest: allOf: - $ref: '#/components/schemas/ExhaustionTimeBurnAlert' - type: object required: - slo - recipients properties: slo: type: object description: Details about the SLO associated with the burn alert. required: - id properties: id: type: string description: Unique identifier (ID) of a SLO. example: id: 2LBq9LckbcA recipients: type: array minItems: 1 description: > A list of [Recipients](/api/recipients/) to notify when an alert fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID. items: $ref: '#/components/schemas/NotificationRecipient' example: - id: abcd123 type: email target: alerts@example.com UpdateExhaustionTimeBurnAlertRequest: allOf: - $ref: '#/components/schemas/ExhaustionTimeBurnAlert' - type: object required: - recipients properties: recipients: type: array minItems: 1 description: > A list of [Recipients](/api/recipients/) to notify when an alert fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID. items: $ref: '#/components/schemas/NotificationRecipient' example: - id: abcd123 type: email target: alerts@example.com BudgetRateBurnAlert: title: Budget Rate allOf: - $ref: '#/components/schemas/BurnAlertSharedParams' - type: object required: - alert_type - budget_rate_window_minutes - budget_rate_decrease_threshold_per_million properties: alert_type: type: string description: > One of the supported alert types: 1. `exhaustion_time`: Notifies when you are about to run out of SLO budget within a specified number of hours. 1. `budget_rate`: Notifies when budget drops by at least a specified percentage within a defined time window. default: exhaustion_time enum: - exhaustion_time - budget_rate example: budget_rate budget_rate_window_minutes: type: integer minimum: 60 description: > Required when `alert_type` is `budget_rate`. Must not be specified when `alert_type` is `exhaustion_time`. Time period (in minutes) over which a budget rate will be calculated. Must be no greater than the associated SLO's time period. example: 120 budget_rate_decrease_threshold_per_million: type: integer minimum: 1 maximum: 1000000 description: > Required when `alert_type` is `budget_rate`. Must not be specified when `alert_type` is `exhaustion_time`. The percent the budget has decreased over the budget rate window, represented as a value out of one million. The alert will fire when this budget decrease threshold is reached. See the table below for some example conversions from desired budget decrease percent to the representation as a value out of one million | Desired percent | Value per million | |-----------------|-------------------| | 0.001% | 1 | | 1% | 10,000 | | 5% | 50,000 | | 99.99% | 999,900 | example: 1000 BudgetRateBurnAlertListResponse: title: Budget Rate allOf: - $ref: '#/components/schemas/BudgetRateBurnAlert' - type: object properties: slo: type: object description: Details about the SLO associated with the burn alert. properties: id: type: string description: Unique identifier (ID) of a SLO. example: id: 2LBq9LckbcA BudgetRateBurnAlertDetailResponse: allOf: - $ref: '#/components/schemas/BudgetRateBurnAlertListResponse' - type: object properties: recipients: type: array minItems: 1 description: > A list of [Recipients](/api/recipients/) to notify when an alert fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID. items: $ref: '#/components/schemas/NotificationRecipient' example: - id: abcd123 type: email target: alerts@example.com CreateBudgetRateBurnAlertRequest: allOf: - $ref: '#/components/schemas/BudgetRateBurnAlert' - type: object required: - slo - recipients properties: slo: type: object description: Details about the SLO associated with the burn alert. required: - id properties: id: type: string description: Unique identifier (ID) of a SLO. example: id: 2LBq9LckbcA recipients: type: array minItems: 1 description: > A list of [Recipients](/api/recipients/) to notify when an alert fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID. items: $ref: '#/components/schemas/NotificationRecipient' example: - id: abcd123 type: email target: alerts@example.com UpdateBudgetRateBurnAlertRequest: title: Budget Rate allOf: - $ref: '#/components/schemas/BudgetRateBurnAlert' - type: object required: - recipients properties: recipients: type: array minItems: 1 description: > A list of [Recipients](/api/recipients/) to notify when an alert fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID. items: $ref: '#/components/schemas/NotificationRecipient' example: - id: abcd123 type: email target: alerts@example.com AnomalySignal: type: string description: | The kind of measurement the Signal is trained on. - `error_rate`: The fraction of erroring requests for the service. - `presence`: Whether the service is producing spans. enum: - error_rate - presence example: error_rate AnomalySignalStatus: type: string description: > The lifecycle status of the Signal. `ineligible` is returned when the underlying service does not meet the conditions required for training. enum: - onboarding - training - active - false - ineligible example: active AnomalySignalSensitivity: type: string description: > How far a measurement must deviate from the trained normal band before the Signal fires. Higher sensitivity narrows the normal band and catches smaller deviations. `sensitivity` is always `null` for `presence` Signals. enum: - low - medium - high example: medium Signal: type: object description: A Honeycomb Anomaly Detection Signal. required: - id - service_name - dataset_slug - environment_slug - measured_signal - enabled - status - sensitivity - auto_investigate - currently_anomalous - last_anomaly_started_at - last_anomaly_ended_at - created_at - updated_at properties: id: type: string description: Unique identifier (ID) of the Signal. readOnly: true example: hcasp_01j9x1yq0k2t8m9n3v4b5r6c7d service_name: type: string description: The name of the service the Signal monitors. readOnly: true example: checkout-api dataset_slug: type: string description: The slug of the dataset the Signal's service reports to. readOnly: true example: checkout-api environment_slug: type: string description: The slug of the environment the Signal belongs to. readOnly: true example: production measured_signal: allOf: - $ref: '#/components/schemas/AnomalySignal' description: The kind of measurement the Signal is trained on. readOnly: true enabled: type: boolean description: >- Whether the Signal is currently enabled. Disabled Signals do not fire. example: true status: allOf: - $ref: '#/components/schemas/AnomalySignalStatus' description: The lifecycle status of the Signal. readOnly: true sensitivity: oneOf: - $ref: '#/components/schemas/AnomalySignalSensitivity' - type: 'null' description: > How far a measurement must deviate from the trained normal band before the Signal fires. Always `null` for `presence` Signals, and `null` for any Signal that has not yet trained. auto_investigate: type: boolean description: >- When `true`, Honeycomb will automatically start an investigation when this Signal fires. readOnly: true example: false currently_anomalous: type: boolean description: Whether the Signal is currently in an anomalous state. readOnly: true example: false last_anomaly_started_at: type: - integer - 'null' description: >- The start time of the most recent anomaly, in seconds since UNIX epoch. `null` when the Signal has never been anomalous. readOnly: true example: 1741089600 last_anomaly_ended_at: type: - integer - 'null' description: >- The end time of the most recent anomaly, in seconds since UNIX epoch. `null` when no anomaly has ended yet, or the Signal is currently anomalous. readOnly: true example: 1741093200 created_at: type: string format: date-time description: The ISO8601-formatted time when the Signal was created. readOnly: true example: '2025-02-14T17:32:11Z' updated_at: type: string format: date-time description: The ISO8601-formatted time when the Signal was last updated. readOnly: true example: '2025-03-01T10:04:22Z' SignalDetailResponse: description: A Signal with its assigned Recipients. allOf: - $ref: '#/components/schemas/Signal' - type: object required: - recipients properties: recipients: type: array description: The Recipients notified when this Signal fires. items: $ref: '#/components/schemas/NotificationRecipient' example: - id: hcar_01jak3ymk8s5cpc2xz3q7d8v9r type: pagerduty details: pagerduty_severity: critical muted: false PaginatedSignalsResponse: type: object description: A page of Signals. required: - signals properties: signals: type: array description: The Signals in this page. items: $ref: '#/components/schemas/Signal' links: $ref: '#/components/schemas/PaginationLinks' UpdateSignalRequest: type: object description: >- Fields to update on a Signal. All fields are optional and only supplied fields are applied. properties: enabled: type: boolean description: Turn the Signal on (`true`) or off (`false`). example: true sensitivity: allOf: - $ref: '#/components/schemas/AnomalySignalSensitivity' description: > Set the sensitivity bucket for `error_rate` Signals. Cannot be set on `presence` Signals or on Signals that have not yet trained. recipients: type: array description: > Replace the Signal's Recipient set with the given list. An empty array clears all Recipients. Each Recipient must be referenced by its `id` from the [Recipients API](/api/recipients/). Requires the **Manage Recipients** permission in addition to **Manage Signals**. items: $ref: '#/components/schemas/SignalRecipient' SignalRecipient: type: object required: - id description: A Recipient assigned to a Signal. properties: id: type: string description: >- The unique identifier of an existing Recipient. Create Recipients via the [Recipients API](/api/recipients/). example: hcar_01jak3ymk8s5cpc2xz3q7d8v9r details: type: object description: >- Per-assignment settings for how this Recipient receives notifications for this Signal. properties: pagerduty_severity: type: string description: >- Severity to use when the assigned Recipient is a PagerDuty Recipient. Rejected for non-PagerDuty Recipients. enum: - critical - error - warning - info example: critical muted: type: boolean description: >- When `true`, the Recipient is muted for this Signal and will not receive notifications. default: false HistoricalAnomaly: type: object description: A resolved anomaly that a Signal previously fired for. required: - id - started_at - ended_at - measurement - normal_range properties: id: type: string description: >- A deterministic identifier for the anomaly, derived from the Signal, its measured kind, and the anomaly's start time. readOnly: true example: 0f8d0f3a-3f8b-5f2b-8f2b-1f2b3f4b5f6b started_at: type: integer description: The time the anomaly started, in seconds since UNIX epoch. readOnly: true example: 1741089600 ended_at: type: integer description: The time the anomaly ended, in seconds since UNIX epoch. readOnly: true example: 1741093200 measurement: type: number description: The measured value that triggered the anomaly. readOnly: true example: 0.42 normal_range: oneOf: - $ref: '#/components/schemas/HistoricalAnomalyNormalRange' - type: 'null' description: >- The trained normal band the measurement exceeded. Always `null` for anomalies on `presence` Signals. HistoricalAnomalyNormalRange: type: object description: The trained normal band a measurement exceeded. required: - lower - upper properties: lower: type: number description: The lower bound of the trained normal band. example: 0.01 upper: type: number description: The upper bound of the trained normal band. example: 0.08 PaginatedHistoricalAnomaliesResponse: type: object description: A page of resolved historical anomalies for a Signal. required: - historical_anomalies properties: historical_anomalies: type: array description: The anomalies in this page, most recent first. items: $ref: '#/components/schemas/HistoricalAnomaly' links: $ref: '#/components/schemas/PaginationLinks' IngestKeyAttributes: title: Ingest Key allOf: - $ref: '#/components/schemas/IngestKeyType' - type: object required: - key_type - name properties: key_type: type: string description: The type of API Key enum: - ingest example: ingest name: type: string description: A human-readable name for the API Key example: us-west-2 collectors key maxLength: 100 disabled: type: boolean description: Whether the API Key is disabled default: false example: false permissions: type: object description: The permissions granted to this Ingest API Key properties: create_datasets: type: boolean description: Whether this API Key can create new Datasets default: false timestamps: type: object readOnly: true properties: created: type: string format: date-time description: The ISO8601-formatted time when the API Key was created. readOnly: true example: '2022-09-22T17:32:11Z' updated: type: string format: date-time description: The ISO8601-formatted time when the API Key was updated. readOnly: true example: '2022-10-31T15:08:11Z' ConfigurationKeyAttributes: title: Configuration Key type: object required: - key_type - name properties: key_type: type: string description: The type of API Key enum: - configuration example: configuration name: type: string description: A human-readable name for the API Key example: us-west-2 collectors key maxLength: 100 disabled: type: boolean description: Whether the API Key is disabled default: false example: false permissions: type: object description: The permissions granted to this Configuration API Key properties: create_datasets: type: boolean description: Whether this API Key can create new Datasets default: false send_events: type: boolean description: Whether this API Key can send Events default: false manage_markers: type: boolean description: Whether this API Key can manage Markers default: false manage_triggers: type: boolean description: Whether this API Key can manage Triggers default: false manage_boards: type: boolean description: Whether this API Key can manage Boards default: false run_queries: type: boolean description: Whether this API Key can run Queries default: false manage_columns: type: boolean description: Whether this API Key can manage Columns and Queries default: false manage_slos: type: boolean description: Whether this API Key can manage SLOs default: false manage_recipients: type: boolean description: Whether this API Key can manage Recipients default: false manage_signals: type: boolean description: Whether this API Key can manage Signals (Anomaly Detection) default: false manage_privateBoards: type: boolean description: Whether this API Key can manage Private Boards default: false read_service_maps: type: boolean description: Whether this API Key can read Service Maps default: false visible_team_members: type: boolean description: > Whether this API Key secret can be accessed by members in the Honeycomb dashboard. The user will only see a redacted key if they aren't an owner when this setting is enabled. This parameter has no effect when used through the API since the API never returns the configuration key secret except at creation. default: false timestamps: type: object readOnly: true properties: created: type: string format: date-time description: The ISO8601-formatted time when the API Key was created. readOnly: true example: '2022-09-22T17:32:11Z' updated: type: string format: date-time description: The ISO8601-formatted time when the API Key was updated. readOnly: true example: '2022-10-31T15:08:11Z' IngestKeyType: type: object required: - key_type properties: key_type: type: string description: The type of API Key enum: - ingest example: ingest UserRelationship: type: object required: - data properties: data: type: object required: - id - type properties: id: type: string description: | The ID of this user. examples: - hcxus_01hzqr5g7jg9qz40xtgx7rjwj0 type: type: string enum: - users CreatorRelationship: readOnly: true description: The User who initially created this resource. oneOf: - $ref: '#/components/schemas/UserRelationship' - type: 'null' EditorRelationship: readOnly: true description: The User who last edited this resource. oneOf: - $ref: '#/components/schemas/UserRelationship' - type: 'null' EnvironmentRelationship: type: object required: - data description: The Environment this object is associated with. properties: data: type: object required: - id - type properties: id: type: string description: The ID of the Environment this object is associated with. example: hxenv_12345678901234567890123456 type: type: string enum: - environments TeamRelationship: type: object required: - team properties: team: type: object required: - data properties: data: type: object required: - id - type properties: id: type: string description: The ID of the Team this object is associated with example: hxctm_12345678901234567890123456 type: type: string enum: - teams ApiKeyObject: type: object properties: id: type: string readOnly: true description: > The unique identifier of the API Key. The last two characters of the prefix define the type of key. `ik` for Ingest Keys and `lk` for Configuration Keys. example: hcxik_12345678901234567890123456 type: type: string readOnly: true enum: - api-keys attributes: $ref: '#/components/schemas/ApiKeyAttributes' relationships: type: object required: - environment properties: environment: $ref: '#/components/schemas/EnvironmentRelationship' creator: $ref: '#/components/schemas/CreatorRelationship' editor: $ref: '#/components/schemas/EditorRelationship' links: type: object properties: self: type: string description: The URL of this resource readOnly: true example: /2/teams/my-team/api-keys/hcxik_12345678901234567890123456 ApiKeyAttributes: type: object oneOf: - $ref: '#/components/schemas/IngestKeyAttributes' - $ref: '#/components/schemas/ConfigurationKeyAttributes' discriminator: propertyName: key_type mapping: ingest: '#/components/schemas/IngestKeyAttributes' configuration: '#/components/schemas/ConfigurationKeyAttributes' IncludedResource: type: object properties: id: type: string readOnly: true description: The unique identifier of the resource example: hcxen_01hznmeqrcq8rz533xrvtc6mk0 type: type: string readOnly: true example: environments attributes: type: object readOnly: true example: name: Production slug: production ApiKeyResponse: type: object required: - data properties: data: $ref: '#/components/schemas/ApiKeyObject' ApiKeyCreateRequest: type: object required: - data properties: data: type: object required: - type - attributes - relationships properties: type: type: string enum: - api-keys attributes: $ref: '#/components/schemas/ApiKeyAttributes' relationships: type: object required: - environment properties: environment: $ref: '#/components/schemas/EnvironmentRelationship' ApiKeyCreateResponse: type: object required: - data properties: data: type: object required: - id - type - attributes - relationships - links properties: id: type: string readOnly: true description: The unique identifier of the API Key example: hcxik_12345678901234567890123456 type: type: string readOnly: true enum: - api-keys attributes: allOf: - $ref: '#/components/schemas/ApiKeyAttributes' - type: object required: - secret properties: secret: type: string description: >- The API Key secret. This is the only time it will be returned. readOnly: true example: '12345678901234567890123456789' relationships: type: object required: - environment properties: environment: $ref: '#/components/schemas/EnvironmentRelationship' creator: $ref: '#/components/schemas/CreatorRelationship' editor: $ref: '#/components/schemas/EditorRelationship' links: type: object properties: self: type: string description: The URL of this resource readOnly: true example: /2/teams/my-team/api-keys/hcxik_12345678901234567890123456 ApiKeyUpdateRequest: type: object required: - data properties: data: oneOf: - $ref: '#/components/schemas/IngestKeyRequest' - $ref: '#/components/schemas/ConfigurationKeyRequest' IngestKeyRequest: type: object title: Ingest Key required: - id - type - attributes properties: id: type: string pattern: ^hcxik_[a-zA-Z0-9]{26}$ description: The unique identifier of the Ingest Key ID with hcxik_ prefix example: hcxik_12345678901234567890123456 type: type: string enum: - api-keys attributes: type: object properties: name: type: string description: A human-readable name for the Ingest Key example: updated key name disabled: type: boolean description: Whether the Ingest Key is disabled example: false ConfigurationKeyRequest: type: object title: Configuration Key required: - id - type - attributes properties: id: type: string pattern: ^hcxlk_[a-zA-Z0-9]{26}$ description: The unique identifier of the Configuration Key ID with hcxlk_ prefix example: hcxlk_12345678901234567890123456 type: type: string enum: - api-keys attributes: type: object properties: name: type: string description: A human-readable name for the API Key example: updated key name disabled: type: boolean description: Whether the API Key is enabled example: false permissions: type: object description: >- The permissions granted to this Configuration API Key. Values omitted will not be replaced. properties: create_datasets: type: boolean description: Whether this API Key can create new Datasets send_events: type: boolean description: Whether this API Key can send Events manage_markers: type: boolean description: Whether this API Key can manage Markers manage_triggers: type: boolean description: Whether this API Key can manage Triggers manage_boards: type: boolean description: Whether this API Key can manage Boards run_queries: type: boolean description: Whether this API Key can run Queries manage_columns: type: boolean description: Whether this API Key can manage Columns and Queries manage_slos: type: boolean description: Whether this API Key can manage SLOs manage_recipients: type: boolean description: Whether this API Key can manage Recipients manage_privateBoards: type: boolean description: Whether this API Key can manage Private Boards read_service_maps: type: boolean description: Whether this API Key can read Service Maps visible_team_members: type: boolean description: > Whether this API Key can be accessed by members. This value is not checked when fetching API keys through the API, there are no permissions check in the API. ApiKeyListResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ApiKeyObject' links: $ref: '#/components/schemas/PaginationLinks' CreateEnvironmentRequest: type: object required: - data properties: data: type: object required: - type - attributes properties: type: type: string enum: - environments attributes: type: object required: - name properties: name: type: string maxLength: 255 description: type: string maxLength: 255 color: $ref: '#/components/schemas/EnvironmentColor' UpdateEnvironmentRequest: type: object required: - data properties: data: type: object required: - id - type - attributes properties: id: type: string type: type: string enum: - environments attributes: type: object properties: description: type: string maxLength: 255 color: $ref: '#/components/schemas/EnvironmentColor' settings: type: object properties: delete_protected: type: boolean description: If true, the environment cannot be deleted. EnvironmentColor: type: string enum: - blue - green - gold - red - purple - lightBlue - lightGreen - lightGold - lightRed - lightPurple Environment: type: object required: - id - type - links - attributes properties: id: type: string type: type: string enum: - environments links: type: object required: - self properties: self: type: string attributes: type: object required: - name - description - color - slug - settings properties: name: type: string description: type: string color: description: > 'classic' color is used only for auto-created Classic environments and cannot be set on any other environment. Classic environments cannot be set to any other color. oneOf: - $ref: '#/components/schemas/EnvironmentColor' - type: string enum: - classic slug: type: string settings: type: object required: - delete_protected properties: delete_protected: type: boolean description: If true, the environment cannot be deleted. EnvironmentResponse: type: object required: - data properties: data: $ref: '#/components/schemas/Environment' EnvironmentListResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Environment' links: $ref: '#/components/schemas/PaginationLinks' AuthV2Response: type: object required: - data properties: included: type: array items: $ref: '#/components/schemas/IncludedResource' example: - id: hcxtm_12345678901234567890123456 type: teams attributes: name: My Team slug: my-team data: type: object required: - id - type - attributes properties: id: type: string readOnly: true description: The unique identifier of the API Key making the request example: hcxik_12345678901234567890123456 type: type: string readOnly: true enum: - api-keys relationships: type: object readOnly: true allOf: - $ref: '#/components/schemas/TeamRelationship' attributes: type: object readOnly: true properties: name: type: string description: A human-readable name for the API Key example: mgmt write key key_type: type: string description: The type of API Key enum: - management disabled: type: boolean description: Whether the API Key is disabled default: false scopes: type: array description: The scopes assigned to this API Key example: - api-keys:write timestamps: type: object properties: created: type: string format: date-time description: The ISO8601-formatted time when the API Key was created. readOnly: true example: '2022-09-22T17:32:11Z' updated: type: string format: date-time description: The ISO8601-formatted time when the API Key was updated. readOnly: true example: '2022-10-31T15:08:11Z' PaginationLinks: type: object description: Links to iterate through the pages of results. required: - next properties: next: type: - string - 'null' description: The URL for the next page of results. readOnly: true example: /2/teams/my-team/api-keys?page[after]=3025fa645ad1100d&page[size]=10 CreateMapDependenciesRequest: type: object description: Create a Map Dependency Request. properties: start_time: type: integer description: > Absolute start time to evaluate dependencies, in seconds since UNIX epoch. Must be <= `end_time` (when `time_range` is not provided). example: 1622548800 end_time: type: integer description: > Absolute end time to evaluate dependencies, in seconds since UNIX epoch. Must be >= `start_time` (when `time_range` is not provided). example: 1622635200 time_range: type: integer default: 7200 minimum: 1 description: > Time range in seconds (minimum 1). Can be used with either `start_time` (seconds after `start_time`), `end_time` (seconds before `end_time`), or without either (seconds before now). example: 7200 filters: type: array description: > Optional list of service nodes to filter dependencies by. Only dependencies involving these nodes will be returned. items: $ref: '#/components/schemas/MapNode' CreateMapDependenciesResponse: type: object description: Response for a Map Dependency Request. properties: request_id: type: string description: | Unique identifier for the Map Dependency Request. example: abc123 status: type: string description: | Status of the Map Dependency Request. enum: - pending - ready - error example: pending GetMapDependenciesResponse: type: object description: Response containing map dependencies data. properties: request_id: type: string description: | Unique identifier for the Map Dependency Request. example: abc123 status: type: string description: | Status of the Map Dependency Request. enum: - pending - ready - error example: ready dependencies: oneOf: - type: array items: $ref: '#/components/schemas/MapDependency' - type: 'null' description: > Array of service dependencies. Null when status is "pending" or "error". links: $ref: '#/components/schemas/PaginationLinks' MapDependency: type: object description: A dependency relationship between two services. properties: parent_node: $ref: '#/components/schemas/MapNode' child_node: $ref: '#/components/schemas/MapNode' call_count: type: integer description: | Number of calls between the parent and child services. example: 142 MapNode: type: object description: A node in the service map (typically a service). required: - name properties: name: type: string description: | Name of the service or node. example: user-service type: type: string description: > Type of the node. Currently only "service" is supported. Defaults to "service" if not specified. enum: - service example: service securitySchemes: configuration_key: type: apiKey name: X-Honeycomb-Team in: header description: > Authenticate using a Honeycomb Configuration Key. Pass the **Token** in the `X-Honeycomb-Team` header: ```http X-Honeycomb-Team: 1234567890123456789012 ``` If you created your key using the API, use `data.attributes.secret`; this is the same value as the **Token** in the UI. To learn how to create a Configuration Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication). ingest_key: type: apiKey name: X-Honeycomb-Team in: header description: > Authenticate using a Honeycomb Ingest Key. Pass the Ingest Key in the `X-Honeycomb-Team` header: ```http X-Honeycomb-Team: hc[x]ik_1234567890123456789012345612345678901234567890123456789012 ``` The key value is the key ID and key secret concatenated with no separator: - If you created your key through the UI, Honeycomb provides the complete value as the **Ingest Key**. - If you created your key using the API, construct the key value by concatenating `data.id` and `data.attributes.secret` with no separator. To learn how to create an Ingest Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication). firehose_access_key: type: apiKey name: X-Amz-Firehose-Access-Key in: header description: > We recommend using a Honeycomb Ingest Key to authenticate, though a Configuration Key will work. To learn more about authenticating requests, visit [API Authentication](/api/authentication). bearerAuth: type: http scheme: bearer description: > Authenticate using a Honeycomb Management Key. Pass the Management Key as a Bearer token in the `Authorization` header: ```http Authorization: Bearer hcxmk_12345678901234567890123456:12345678901234567890123456789012 ``` Construct the key value by joining the **Key ID** and **Secret** with a colon (`:`). To learn how to create a Management Key, visit [Manage Team API Keys](/configure/teams/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication). bearerFormat: HONEYCOMB_KEY_ID:HONEYCOMB_KEY_SECRET