We use cookies or similar technologies to personalize your online experience and tailor marketing to you. Many of our product features require cookies to function properly. Your use of this site and online product constitutes your consent to these personalization technologies. Read our Privacy Policy to find out more.

X

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 API 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: YOUR_API_KEY" \
  -H "X-Honeycomb-Event-Time: 2018-02-09T02:01:23.115Z" \
  -d '{"method":"GET","endpoint":"/foo","shard":"users","dur_ms":32}'

Example Response

# A successful POST returns an HTTP 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 API 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 API 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 API 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":"2018-02-09T02:01:23.115Z",
          "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.

Limits

There are a few limits to note in regards to the events API.

Size limitations may be addressed by gzipping request bodies. Be sure to set the Content-Encoding: gzip like below:

$ curl https://api.honeycomb.io/1/batch/gziptest -X POST \
    -H "X-Honeycomb-Team: APIKEY" \
    -H "Content-Encoding: gzip" \
    -H "Content-Type: application/json" \
    --data-binary @data.json.gz

Timestamp Backfill Considerations

As noted above, you can specify an exact timestamp for a given event (differing from the time when the event was received) to backfill data from the past into Honeycomb.

If you choose to do so, we recommend that you do not send events from very different time ranges if possible. The Honeycomb storage engine will work most efficiently when it does not have to handle large gaps in the timestamps of the ingested events. Where possible, keep the timestamps of the events you are sending close to the current time and to each other.