Columns API | Honeycomb

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

Columns API

Columns are fields in the events you send. You might use this API to:

  • See what columns are available in your dataset
  • Add columns in advance of incoming data so you can create queries or derived columns that refer to these columns
  • Add a description
  • Hide or unhide a column
  • Delete a column

This API parallels the behavior of the Schema tab within a Dataset’s Settings UI.

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 Manage Queries and Columns permission. Learn more about API keys.

Fields on a Column 

Columns have the following fields:

Field Type Optional Notes
id string read-only Unique identifier, returned in response bodies
key_name string no Name of the column
hidden boolean yes, default=false if true, the column is excluded from autocomplete and raw data field lists
description string yes, default=""
last_written string read-only ISO8601 formatted time the column was last written to (received event data)
type string enum (“string”, “float”, “integer”, “boolean”) yes, default=“string”
created_at string read-only ISO8601 formatted time the column was created
updated_at string read-only ISO8601 formatted time the column was updated

Create a Column 

Columns are created by sending a POST request to /1/columns/<DATASET_NAME>

The body should be a JSON encoded object containing at least key_name and it must not contain an id. All other fields are optional.

Response status should be 201, and the body will contain the created object, including its id.

Create Example Request  

curl https://api.honeycomb.io/1/columns/$DATASET_SLUG \
    -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '{"key_name": "my_new_column", "type": "integer"}'

Create Example Response  

{
  "id": "yUheCUmgZ8p",
  "key_name": "my_new_column",
  "hidden": false,
  "description": "",
  "type": "integer",
  "last_written": "2022-07-26T22:38:05Z",
  "created_at": "2022-07-26T22:38:04Z",
  "updated_at": "2022-07-26T22:38:04Z"
}

Update a Column 

Update a Column by sending a PUT request to /1/columns/<dataset>/<column_id>.

The PUT request should have as its body a JSON object containing all the user-settable fields for this Column, including any updated values. (That is, it is a PUT request, not a PATCH applying a partial update.)

When a Column has been successfully updated, the API returns code 200 and the updated Column as the body of the response.

Update Example Request  

curl https://api.honeycomb.io/1/columns/$DATASET_SLUG/$COLUMN_ID \
  -X PUT \
  -H "X-Honeycomb-Team: YOUR_API_KEY" \
  -d '{"key_name": "my_new_column", "type": "integer", "hidden": true, "description": "Heres my new column."}'

Update Example Response  

{
  "id": "yUheCUmgZ8p",
  "key_name": "my_new_column",
  "hidden": true,
  "description": "Heres my new column.",
  "type": "integer",
  "last_written": "2022-06-26T22:38:05Z",
  "created_at": "2021-07-26T22:38:04Z",
  "updated_at": "2022-07-26T22:38:05Z"
}

Delete a Column 

After a DELETE request, a successful response will have a status code 204 and an empty body.

Deleted columns are no longer queryable, but data in existing permalinks (query results and trace views) will remain stored and available at those links.

Delete Example Request  

curl https://api.honeycomb.io/1/columns/$DATASET_SLUG/$COLUMN_ID \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -X DELETE

Delete Example Response: Error Column in use by a Derived Column  

409 Conflict
{
  "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": "Column is in use by 1 derived columns.",
  "error": "Column is in use by 1 derived columns."
}

Get One Column 

A singular Column in a dataset may be retrieved by sending a GET request to /1/columns/<DATASET_NAME>/<COLUMN_ID>.

Get One Column Example Request  

curl https://api.honeycomb.io/1/columns/$DATASET_SLUG/$COLUMN_ID \
    -X GET \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get One Column Example Response  

{
  "id": "D1TaSJzsEoX",
  "key_name": "api_column",
  "hidden": false,
  "description": "",
  "type": "string",
  "last_written": "2022-07-26T22:38:05Z",
  "created_at": "2021-07-26T22:38:04Z",
  "updated_at": "2021-07-26T22:38:04Z"
}

Get One Column by KeyName 

A singular Column in a dataset may be retrieved by sending a GET request to /1/columns/<DATASET_SLUG>?key_name=<KEY_NAME>.

Get One Column by KeyName Example Request  

curl https://api.honeycomb.io/1/columns/$DATASET_SLUG?key_name=$KEY_NAME \
    -X GET \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get One Column by KeyName Example Response  

{
  "id": "yUheCUmgZ8p",
  "key_name": "my_new_column",
  "hidden": true,
  "description": "Heres my new column.",
  "type": "integer",
  "last_written": "2022-07-26T22:38:05Z",
  "created_at": "2021-07-26T22:38:04Z",
  "updated_at": "2021-07-26T22:38:04Z"
}

List All Columns 

All the Columns in a dataset may be retrieved by sending a GET request to /1/columns/<DATASET_NAME>.

A successful response will return HTTP 200 and a JSON list of all Column objects for the dataset.

List All Example Request  

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

Did you find what you were looking for?

Table of Contents