Datasets

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.

Create a Dataset

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.

Securityconfiguration_key
Request
Request Body schema: application/json
required

The dataset will be created within the environment associated with your API key.

name
required
string [ 1 .. 255 ] characters

The name of the dataset.

description
string [ 0 .. 1024 ] characters
Default: ""

A description for the dataset.

expand_json_depth
integer [ 0 .. 10 ]
Default: 0

The maximum unpacking depth of nested JSON fields.

Responses
200

OK - Dataset already exists

201

Created

401

Unauthorized

403

Forbidden

409

Conflict

422

Validation Failed

default

Error

post/1/datasets
Request samples
application/json
{
  • "name": "string",
  • "description": "A nice description of my dataset",
  • "expand_json_depth": 3
}
Response samples
application/json
{
  • "name": "My Dataset!",
  • "description": "A nice description of my dataset",
  • "settings": {
    },
  • "expand_json_depth": 3,
  • "slug": "my-dataset-",
  • "regular_columns_count": 100,
  • "last_written_at": "2022-07-21T18:39:23Z",
  • "created_at": "2022-09-22T17:32:11Z"
}

List All Datasets

Lists all Datasets for an environment.

Note: For Honeycomb Classic users, all datasets in Classic are returned.

Securityconfiguration_key
Responses
200

Success

401

Unauthorized

default

Error

get/1/datasets
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Get a Dataset

Get a single Dataset by slug.

Securityconfiguration_key
Request
path Parameters
datasetSlug
required
string

The dataset slug.

Responses
200

Success

401

Unauthorized

404

Not Found

default

Error

get/1/datasets/{datasetSlug}
Request samples
Response samples
application/json
{
  • "name": "My Dataset!",
  • "description": "A nice description of my dataset",
  • "settings": {
    },
  • "expand_json_depth": 3,
  • "slug": "my-dataset-",
  • "regular_columns_count": 100,
  • "last_written_at": "2022-07-21T18:39:23Z",
  • "created_at": "2022-09-22T17:32:11Z"
}

Delete a Dataset

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.

Securityconfiguration_key
Request
path Parameters
datasetSlug
required
string

The dataset slug.

Responses
202

Deleted

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict

default

Error

delete/1/datasets/{datasetSlug}
Request samples
Response samples
{
  • "error": "unknown API key - check your credentials"
}

Update a Dataset

Update a Dataset's settings.

Securityconfiguration_key
Request
path Parameters
datasetSlug
required
string

The dataset slug.

Request Body schema: application/json

Update a Dataset's settings.

All fields must be specified, as omitting one will have the effect of reverting the setting to the default.

description
required
string [ 0 .. 1024 ] characters
Default: ""

A description for the dataset.

expand_json_depth
required
integer [ 0 .. 10 ]
Default: 0

The maximum unpacking depth of nested JSON fields.

object
Responses
200

Updated

401

Unauthorized

404

Not Found

put/1/datasets/{datasetSlug}
Request samples
application/json
{
  • "expand_json_depth": 3,
  • "description": "my updated description",
  • "settings": {
    }
}
Response samples
application/json
{
  • "name": "My Dataset!",
  • "slug": "my-dataset-",
  • "description": "my updated description",
  • "settings": {
    },
  • "expand_json_depth": 3,
  • "created_at": "2022-07-21T18:39:23Z",
  • "last_written_at": "2022-09-22T17:32:03Z",
  • "regular_columns_count": 100
}