1. Docs
2. API
3. Events API

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.

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 our Support team via support.honeycomb.io, or email at 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.

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

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 

Failure Responses 

Did you find what you were looking for?

Yes No

Additional Feedback (Optional)

---

If you have questions, join our Pollinators Community Slack, or for Pro/Enterprise users, contact Support at support.honeycomb.io, or email at support@honeycomb.io.

Submit