Check here to consent to cookies or similar technologies to personalize your online experience and send you relevant offers. Our product cannot be used without some of these personalization technologies, so your use of the product (after login) constitutes consent to those necessary cookies. Read our Privacy Policy to find out more.

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: 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 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":"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.