logo

Query Annotations

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.

Create a Query Annotation

Create a Query Annotation for the specified query ID.

Securityapi_key
Request
path Parameters
datasetSlug
required
string

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

Request Body schema: application/json
required
name
required
string [ 1 .. 80 ] characters

A name for the Query.

description
string <= 280 characters

A description of the Query.

query_id
required
string

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.

Responses
201

Created

400

Bad Request

403

Forbidden

404

Not Found

default

Error

post/1/query_annotations/{datasetSlug}
Request samples
application/json
{
  • "name": "My Named Query",
  • "description": "A nice description of My Named Query",
  • "query_id": "mabAMpSPDjH"
}
Response samples
application/json
{
  • "name": "My Named Query",
  • "description": "A nice description of My Named Query",
  • "query_id": "mabAMpSPDjH",
  • "id": "sGUnkBHgRFN",
  • "created_at": "2022-10-26T21:36:04Z",
  • "updated_at": "2022-12-04T08:14:26Z"
}

List Query Annotations

List all Query Annotations in the specified dataset.

Securityapi_key
Request
path Parameters
datasetSlug
required
string

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

Responses
200

Success

404

Not Found

default

Error

get/1/query_annotations/{datasetSlug}
Request samples 
Response samples 
application/json
[
  • {
    }
]
Get a Query Annotation
Get a Query Annotation by its ID.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug or use __all__ for endpoints that support environment-wide operations.


 
queryAnnotationId
required
string
The unique identifier (ID) of the annotation.


 
Responses 
200
Success


404
Not Found


default
Error


get/1/query_annotations/{datasetSlug}/{queryAnnotationId}
Request samples 
Response samples 
application/json
{
  • "name": "My Named Query",
  • "description": "A nice description of My Named Query",
  • "query_id": "mabAMpSPDjH",
  • "id": "sGUnkBHgRFN",
  • "created_at": "2022-10-26T21:36:04Z",
  • "updated_at": "2022-12-04T08:14:26Z"
}
Update a Query Annotation
Update a Query Annotation by specifying its ID. The Query ID associated with the Query Annotation cannot be updated. Partial updates are not supported.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug or use __all__ for endpoints that support environment-wide operations.


 
queryAnnotationId
required
string
The unique identifier (ID) of the annotation.


 
Request Body schema: application/json
required
name
required
string  [ 1 .. 80 ] characters 
A name for the Query.


 
description
string  <= 280 characters 
A description of the Query.


 
query_id
required
string
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.


 
Responses 
200
Success


400
Bad Request


404
Not Found


default
Error


put/1/query_annotations/{datasetSlug}/{queryAnnotationId}
Request samples 
application/json
{
  • "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"
}
Response samples 
application/json
{
  • "name": "My Updated Annotation",
  • "description": "A nice description of My Update Annotation",
  • "query_id": "mabAMpSPDjH"
}
Delete a Query Annotation
Delete a Query Annotation by specifying its ID.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug or use __all__ for endpoints that support environment-wide operations.


 
queryAnnotationId
required
string
The unique identifier (ID) of the annotation.


 
Responses 
204
Success - no content


404
Not Found


default
Error


delete/1/query_annotations/{datasetSlug}/{queryAnnotationId}
Request samples 
Response samples 
{
  • "error": "dataset not found"
}
➔ Next to Query Data