API Reference

The Honeycomb API supports two endpoints—one for Events, the standard unit of data in Honeycomb, and one for Markers, a supplementary way to mark specific points in time across datasets. All requests should be made via HTTPS to api.honeycomb.io.

Events

We accept individual events as an HTTP POST request:

URL

The events endpoint is /1/events/. The resource to which you’re POSTing your event is the dataset name, so the full URL to which you should POST an event is:

https://api.honeycomb.io/1/events/<DATASET_NAME>

Dataset names are case insensitive—POSTs to MyDatasET will land in the same dataset as mydataset. Names may contain spaces or other special characters so long as they are URL encoded (for example My%20Dataset will show up in the UI as “My Dataset”).

Headers

The Team Write Key, Sample Rate, and Timestamp are all specified as HTTP headers.

• Write Key header: X-Honeycomb-Team (required)
• Timestamp: X-Honeycomb-Event-Time (optional, defaults to the time the server receives the event) Must be in RFC3339 format (eg YYYY-MM-DDTHH:MM:SS.ssssZ0000).
• Sample Rate: X-Honeycomb-Samplerate (optional, defaults to 1)

Body

The body of the POST should be a JSON encoded object containing key/value pairs. As an example, to report a GET request to /foo that hit the users db shard and took 32ms:

{"method":"GET","endpoint":"/foo","shard":"users","dur_ms":32}

Supported data types:

• strings
• numbers
• bools

Numbers are stored as floats by default, but you can configure your dataset schema to store them as integers.

To store numbers as integers: * Navigate to Settings > Schema for the dataset you want to configure and set the Data Type column value for that row to “integer”.

Size limits:

• Body: The body must not be empty, and must be less than 100KB.
• String Fields: Each string field has a maximum length of 64KB.
• Number Fields: Ints and Floats are both 64bit.

Responses

An empty 200 response indicates that the event has been queued for processing.

More detail on all the possible API response codes and content is below.

Example

This example sends an API request event to Honeycomb. It is in the TestViaCurl dataset.

# Example Request
curl https://api.honeycomb.io/1/events/TestViaCurl -X POST \
  -H "X-Honeycomb-Team: WRITEKEY" \
  -d '{"method":"GET","endpoint":"/foo","shard":"users","dur_ms":32}'

# Example Response: 200 OK

API Responses

List of common response codes and returned content. (If you get a response not listed here and it’s not clear what it means, please tell us and we’ll fix it!)

Successful responses

Failure responses

Batched Events

The batch endpoint is currently:

https://api.honeycomb.io/1/batch/<DATASET_NAME>

The only expected header is X-Honeycomb-Team, which is your Team Write Key. Overriding timestamps or sample rates should happen inside each event.

The JSON payload should have the structure: [ { "data": { "key1": "value1", "key2": 2.0 } }, ... ], where the array should contain one or more JSON objects representing Events. Each Event contains its payload under the "data" key, and optionally "time" or "samplerate" values can be included as well.

# Example Request
curl https://api.honeycomb.io/1/batch/Dataset%20Name -X POST \
  -H "X-Honeycomb-Team: 010afd48c74f48422fd4427c17aa9dba" \
  -d '[
        {
          "time":"2017-02-09T02:00:00Z",
          "data":{"key1":"val1","key2":"val2"}
        },
        {
          "data":{"key3":"val3"}
        }
      ]'

# Example Response
[
  { "status":202 },
  { "status":202 }
]

An empty 202 response indicates that the event has been queued for processing.

Markers

Markers are for indicating points in time on your graphs where interesting things happen, such as deploys or outages. You can list, create, update, and delete markers.

All marker endpoints operate on a dataset and use the Team Write Key to authenticate.

Fields on a marker

Marker objects have the following assignable fields. All fields are optional, and may be modified at any time.

• start_time: Indicates the time the marker should be placed. If missing, defaults to the time the request arrives at the API. Expressed in Unix Time, aka seconds since the epoch
• end_time: not yet implemented on graphs, but will allow you to show a marker happening over a time range (such as a 5 minute deploy). Expressed in Unix Time, aka seconds since the epoch
• message: a string describing this specific marker. This string will appear above the marker line on a graph
• type: a string grouping similar markers, eg ‘deploys’. All markers of the same type will appear in the same color on the graph
• url: a target for the marker. If you click on the marker text, it will take you to this URL. For a deploy, it might be a link to the build system showing the build log for the version that was deployed

When a marker is created or updated, the following fields are assigned. They may not be modified.

• id: The marker ID is a 6 character hexadecimal string and is assigned on marker creation
• created_at: The time the marker was created
• updated_at: The time of the most recent modification to the marker. It is updated every time the marker is changed.
• color: You can assign a color to a marker type in the Dataset Advanced settings page in the UI. The color field will be populated when you list events.

Headers

The Team Write Key is the only header accepted for markers. It is required.

Create a marker

Markers are created by sending a POST request to /1/markers/<DATASET_NAME>

The Marker body should be a JSON encoded object including as many of the marker fields as desired. ID may not be set during creation.

When a marker is successfully created, the API will respond with HTTP status 200 and will return a JSON object representing that marker.

An example, creating a deploy marker on the TestViaCurl dataset:

curl https://api.honeycomb.io/1/markers/TestViaCurl -X POST  \
    -H "X-Honeycomb-Team: WRITEKEY"  \
    -d '{"message":"backend deploy #123", "type":"deploy", "start_time":1471040808}'
# {"created_at":"2016-08-13T05:39:42Z","updated_at":"2016-08-13T05:39:42Z","start_time":1471040808,"message":"backend deploy #123","type":"deploy","id":"d1c84ec0"}

Update a marker

Any of the modifiable fields in a marker can be updated by sending a PUT request to /1/markers/<dataset>/<marker_id>.

The PUT request should have as its body a JSON object containing all the user-settable fields for this marker, including any updated values. If you do not include an existing field in the payload, it will be erased.

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

As an example, this curl request will change the start time of the marker created above:

curl https://api.honeycomb.io/1/markers/TestViaCurl/d1c84ec0 -X PUT  \
    -H "X-Honeycomb-Team: WRITEKEY"  \
    -d '{"message":"backend deploy #123", "type":"deploy", "start_time":1471067108}'
# {"created_at":"2016-08-13T05:39:42Z","updated_at":"2016-08-13T05:39:42Z","start_time":1471067108,"message":"backend deploy #123","type":"deploy","id":"d1c84ec0"}

Delete a marker

Markers may be deleted by sending a DELETE request to /1/markers/<dataset>/<marker_id>.

The body of the DELETE request should be empty.

When the marker has been successfully deleted, the API will respond with 200 and the deleted marker in the body of the response.

As an example, this curl request will delete the marker we created and modified above:

curl https://api.honeycomb.io/1/markers/TestViaCurl/d1c84ec0 -X DELETE  \
    -H "X-Honeycomb-Team: WRITEKEY"
# {"created_at":"2016-08-13T05:39:42Z","updated_at":"2016-08-13T05:39:42Z","start_time":1471067108,"message":"backend deploy #123","type":"deploy","id":"d1c84ec0"}

List all markers

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

The response will be HTTP 200 and a JSON list of marker objects.