Events API

You can send events to Honeycomb with the Events API, either individually or batched. 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}

Supported data types:

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:

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.

You are currently logged in to the team, so we have populated the write key here to the first write key for that team.

# 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

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.