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.

The Events API endpoints are the lowest-level way to send Events to Honeycomb. This should be your last resort!

If you are looking to instrument an application and are unsure where to start, read about how to Send Data to Honeycomb. If you are building a tracing or metrics library, you probably want OpenTelemetry instead. The Beelines or Libhoneys are likely a better choice if you can use them.

Anatomy of an Event 

An Event is a collection of key-value pairs, represented as a JSON object. For example, to report a GET request to /foo that hit the users db shard and took 32ms:

{"method":"GET","endpoint":"/foo","shard":"users","duration_ms":32}

Events may additionally include the following metadata:

  • Timestamp: The time when the event occurred. To send this with a single event, use a header; in batched events, send it in the body. Should be in RFC3339 high precision format (for example, YYYY-MM-DDTHH:MM:SS.mmmZ). May be a Unix epoch (seconds since 1970) with second or greater precision (for example, 1452759330927). Optional. If not set, defaults to the time the API receives the event.
  • Sample Rate: An integer representing the denominator in the fraction 1/n when client-side sampling has been applied. To send this with a single event, use a header; in batched events, send it in the body. Optional. If not set, defaults to 1, meaning “not sampled”. See Sampling for more detail.

Timestamp 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.

Additionally, timestamps are only accepted up to one hour in the future. Timestamps further out will be disregarded and replaced with the time of receipt. If you have a use case which requires sending future events, please contact Honeycomb Support via support@honeycomb.io.

Data Types 

Honeycomb supports basic data types for the values of each Event attribute:

  • 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”.

Limits 

  • Event: 2,000 fields per event. The entire event must be less than 100KB of uncompressed JSON.
  • Dataset: 10,000 fields per dataset.
  • String Fields: Each string field has a maximum length of 64KB.
  • Number Fields: Integers and Floats are both 64-bit.

Send Batched Events 

https://api.honeycomb.io/1/batch/<DATASET_NAME>

Dataset names are case insensitive. POST requests to MyDatasET will land in the same dataset as mydataset. Names may contain URL-encoded spaces or other special characters, but not URL-encoded slashes. 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.

Batched Events Headers 

The only required header is X-Honeycomb-Team, which is your API key.

Batched Events Body 

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" and/or "samplerate" can be included as well.

  • The request body is limited to raw (potentially compressed) size of 5MB.
  • The maximum number of distinct columns (fields) allowed in any individual event is 2000.

Size limitations may be addressed by compressing request bodies with gzip or zstd compression. Be sure to set the Content-Encoding: to gzip or zstd similar to below:

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

Example Request 

curl https://api.honeycomb.io/1/batch/Dataset%20Name -X POST \
  -H "X-Honeycomb-Team: YOUR_API_KEY" \
  -d '[
        {
          "time": "2006-01-02T15:04:05.99Z",
          "samplerate": 10,
          "data":{"key1":"val1","key2":"val2"}
        },
        {
          "time": "2006-01-02T15:04:05.99Z",
          "data":{"key3":"val3"}
        }
      ]'

Example Response 

The response to a batched event will include the response code for each event sent, in order:

[{ "status": 202 }, { "status": 202 }]

An empty 202 response indicates that the event has been queued for processing.

Learn more details on all the possible API response codes and content.

Send a Single Event 

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

Using this endpoint for anything more than testing is highly discouraged. Sending events in batches will be much more efficient and should be preferred if at all possible.

https://api.honeycomb.io/1/events/<DATASET_NAME>

A Dataset name may contain URL-encoded spaces or other special characters, but not URL-encoded slashes.

Single Event Headers 

The Team API key, Sample Rate, and Timestamp are all specified as HTTP headers.

  • X-Honeycomb-Team: API Key. Required.
  • X-Honeycomb-Event-Time: The Event’s timestamp. Optional. Defaults to server time.
  • X-Honeycomb-Samplerate: Optional. Defaults to 1.

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

Single Event Body 

The body of the POST should be a JSON encoded object containing key/value pairs:

{"method":"GET","endpoint":"/foo","shard":"users","duration_ms":32}
  • The request body is limited to raw (potentially compressed) size of 100KB.
  • The maximum number of distinct columns (fields) allowed in an event is 2000.

Responses 

An empty 200 response indicates that the event has been queued for processing.

Learn more details on all the possible API response codes and content.

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","duration_ms":32}'

Example Response 

# A successful POST returns an HTTP 200 OK

API Response Codes 

Below are a list of common response codes and their meanings. There may be other response codes not listed here.

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 did not match a known API key. Check https://ui.honeycomb.io/account to verify your API key.
400 "event has an invalid key" The X-Honeycomb-Team header is blank and lacks an API Key.
400 "request body is too large" See above for size limits.
400 "event has too many columns" The event has reached the maximum number of columns. See above for limits.
400 "dataset has too many columns" The dataset has reached the maximum number of columns. See above for limits.
400 "request body should not be empty" The body is empty, or blank.
400 "request body is malformed and cannot be read" 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 denylist" Occasionally we will block some or all traffic coming in to the API server. If your events are getting dropped due to a denylist and you do not expect it, contact us and we will 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!

Did you find what you were looking for?