Events API | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

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

The Events API endpoints support both the Honeycomb-specific JSON format and the OpenTelemetry standard OTLP data format.

Events  🔗

We accept individual events as an HTTP POST request as a JSON-encoded object of key-value pairs.

URL  🔗

The events endpoint starts with /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.

  • API key header: X-Honeycomb-Team (required)
  • Timestamp: X-Honeycomb-Event-Time (optional, defaults to the time the server receives the event) Should be in RFC3339 high precision format (for example, YYYY-MM-DDTHH:MM:SS.mmmZ). May be a unix epoch timestamp (seconds since 1970) with second or greater precision (for example, 1452759330927).
  • Sample Rate: X-Honeycomb-Samplerate (optional, defaults to 1) An integer representing the denominator in the fraction 1/n. For example, a sample rate of 5 means that 1/5 (20% or “one in every 5”) of your events will be sent to Honeycomb.

The API key must have the Send Events permission. Learn more about API Keys.

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:

  • strings
  • numbers
  • booleans

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:

  • Body: The body must not be empty, and must be less than 100KB.
  • String Fields: Each string field has a maximum length of 64KB.
  • Number Fields: Integers and Floats are both 64bit. Numbers default to floats.

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.

Example Request  🔗

$ curl https://api.honeycomb.io/1/events/test-via-curl -X POST \
  -H "X-Honeycomb-Team: YOUR_API_KEY" \
  -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. Values of "time" (a quoted string) or "samplerate" (a number) can be included as well.

Example Batch Request  🔗

$ curl https://api.honeycomb.io/1/batch/Dataset%20Name -X POST \
  -H "X-Honeycomb-Team: 010afd48c74f48422fd4427c17aa9dba" \
  -d '[
        {
          "data":{"key1":"val1","key2":"val2"}
        },
        {
          "data":{"key3":"val3"}
        }
      ]'

Example Batch 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:

  • Requests to the individual event endpoint have a maximum request body size of 100KB.
  • Requests to the batched events endpoint have a maximum request body size of 5MB. Individual event bodies in the batch are limited to 100KB each.
  • The maximum number of distinct columns (fields) allowed per event is 2000.

Size limitations may be addressed by gzip ping request bodies. Be sure to set the Content-Encoding: gzip similar to 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.