Manage datasets — the columnar tables that hold ingested events for a service — and dataset definitions that map well-known OpenTelemetry fields (service.name, trace.parent_id, span.kind, etc.) to the columns Honeycomb uses for trace assembly, BubbleUp, and Service Map rendering.
openapi: 3.1.0
info:
title: Honeycomb Datasets 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 <a href="https://docs.honeycomb.io/troubleshoot/community/">Pollinators Slack</a> or to <a href="https://support.honeycomb.io/">Honeycomb
Support</a>.
'
externalDocs:
url: https://docs.honeycomb.io
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- 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/).
'
paths:
/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-21 18:39:23+00:00
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/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.\n**Note**: In order to **CLEAR** a\
\ column of a Dataset definition set the column\u2019s name field to an empty string.\n"
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'
components:
schemas:
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'
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
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
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.
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
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.
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
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
Error:
x-tags:
- Errors
type: object
description: A legacy error, containing only a textual description.
properties:
error:
type: string
readOnly: true
headers:
RateLimitPolicy:
description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"X;w=Y\".\nWhere:\n - X is the maximum number of requests allowed in a window\n\
\ - Y is the size of the window in seconds\n"
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
RateLimit:
description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"limit=X, remaining=Y, reset=Z\".\nWhere:\n - X is the maximum number of requests\
\ allowed in the window\n - Y is the number of requests remaining in the window\n - Z is the number of seconds until the limit resets\n"
schema:
type: string
example: limit=100, remaining=50, reset=60
responses:
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'
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'
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'
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'
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'
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 li
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/honeycomb-io/refs/heads/main/openapi/honeycomb-datasets-api-openapi.yml