This API allows you to create a dataset. Datasets are created automatically for you when events are received. The intended use case of this API is for creating a dataset programmatically in a Config-as-Code/Infrastructure-as-Code context as a preface to using the Columns or Derived Columns APIs.
A Dataset consists of a name, description, and expand_json_depth.
name: (required) The name of the dataset.description: A longer description for dataset. Defaults to empty string, or “”.expand_json_depth: The maximum unpacking depth of nested JSON fields. Defaults to 0.
The only expected header is X-Honeycomb-Team, which is your API key, and it is required.
The API key must have the Create Datasets permission.
Learn more about API keys.
Datasets are created by sending a POST request to /1/datasets.
The dataset will be created within the environment associated with your API key.
The body should be a JSON encoded object containing a name.
Response status should be 201, and the body will contain the created dataset, including its slug.
curl https://api.honeycomb.io/1/datasets \
-X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '{"name": "another dataset"}'
{
"name": "another dataset",
"description": "",
"slug": "another-dataset",
"expand_json_depth": 0,
"created_at": "2022-07-21T18:39:23Z",
"last_written_at": null
}
curl https://api.honeycomb.io/1/datasets \
-X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '{"name": "my dataset!", "description": "my dataset described!", "expand_json_depth": 2}'
{
"name": "my dataset!",
"description": "my dataset described!",
"slug": "my-dataset-",
"expand_json_depth": 2,
"created_at": "2022-07-21T18:39:23Z",
"last_written_at": null,
"regular_columns_count": 0
}
A singular Dataset may be retrieved by sending a GET request to /1/datasets/$DATASET_SLUG.
last_written_at is the timestamp of when data was last ingested for this Dataset.
The value will be null if no data has been received yet.
regular_columns_count is the total number of unique fields for this Dataset.
The value will be null if the dataset does not contain any fields yet.
curl https://api.honeycomb.io/1/datasets/my-dataset- \
-X GET \
-H "X-Honeycomb-Team: YOUR_API_KEY"
{
"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": 100
}
All Datasets for an environment may be retrieved by sending a GET request to /1/datasets.
In Honeycomb Classic, all datasets in Classic are returned.
curl https://api.honeycomb.io/1/datasets \
-X GET \
-H "X-Honeycomb-Team: YOUR_API_KEY"
[
{
"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
}
]
A Dataset can be updated by sending a PUT request to /1/dataset/$DATASET_SLUG.
The body of the PUT should be a JSON encoded object containing key/value pairs.
If you do not include an existing field in the payload, it will be erased.
curl https://api.honeycomb.io/1/datasets \
-X PUT \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '{"description": "new description", "expand_json_depth": 9}'
{
"name": "another dataset",
"description": "new description",
"slug": "another-dataset",
"expand_json_depth": 9,
"created_at": "2022-07-21T18:39:23Z",
"last_written_at": null
}
Did you find what you were looking for?