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. (However, you might find it easier to get events in with one of the integrations designed for your tool.)

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”). The first event received for a dataset determines the casing of the displayed name; all subsequent variations in casing will use the originally specified case.

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

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.
403 "event dropped due to administrative throttling" When ingested events exceed the monthly limit for an extended period of time, your team may enter a throttled state, with a percentage of events being dropped. Please contact us for assistance in getting out of a throttled state.
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.