Datasets API | Honeycomb

Honeycomb.io Documentation
  1. Docs
  2. API
  3. Datasets API

Datasets API

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.

Fields on a Dataset 

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.

Authorization and Headers 

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.

Create a Dataset 

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.

Create Example Request (minimal)  

curl https://api.honeycomb.io/1/datasets \
    -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '{"name": "another dataset"}'

Create Example Response (minimal)  

{
  "name": "another dataset",
  "description": "",
  "slug": "another-dataset",
  "expand_json_depth": 0,
  "created_at": "2022-07-21T18:39:23Z",
  "last_written_at": null
}

Create Example Request (all fields)  

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}'

Create Example Response (all fields)  

{
  "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
}

Get One Dataset 

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.

Get One Example Request  

curl https://api.honeycomb.io/1/datasets/my-dataset- \
    -X GET \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get One Example Response  

{
  "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
}

Get All Datasets 

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.

Get All Example Request  

curl https://api.honeycomb.io/1/datasets \
    -X GET \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get All Example Response  

[
  {
    "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
  }
]

Update a Dataset 

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.

Update Example Request  

curl https://api.honeycomb.io/1/datasets \
    -X PUT \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '{"description": "new description", "expand_json_depth": 9}'

Update Example Response  

{
  "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?

Table of Contents