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.

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}

Size limits:

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, with an example writekey

# Example Request
curl https://api.honeycomb.io/1/events/TestViaCurl -X POST \
  -H "X-Honeycomb-Team: YOUR_WRITE_KEY" \
  -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

Status Code Body Meaning
200 empty The event was successfully enqueued for storage
200 request dropped due to server side sampling Server-side sampling is enabled for this dataset, and this event was dropped as part of that sampling policy

Failure responses

Status Code Body Meaning
400 unknown Team key - check your credentials The X-Honeycomb-Team header didn’t match a known team. Check https://ui.honeycomb.io/account to verify your Team write key
400 request body is too large See above for size limits
400 request body is malformed and cannot be read as JSON The API failed to decode the body as JSON.
429 event dropped due to administrative blacklist Occasionally we will block some or all traffic coming in to the API server. If your events are getting dropped due to a blacklist and you don’t expect it, contact us and we’ll work with you.
429 request dropped due to rate limiting We have rate limits set to prevent any one data source from overwhelming our system. If you would like your rate limit raised, contact us!

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.

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

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: YOUR_WRITE_KEY"  \
    -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/<dateset>/<marker_id>.

The PUT request should have as its body a JSON object containing only the fields you wish to change in the marker.

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: YOUR_WRITE_KEY"  \
    -d '{"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/<dateset>/<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: YOUR_WRITE_KEY"
{"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.