logo

Events

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

If unsure where to start when instrumenting an application, read about how to Send Data to Honeycomb.

If you are building a tracing or metrics library, we recommend using OpenTelemetry.

Authorization

It is recommended that an Ingest API key is used for sending events.

A Configuration API key will work, and must have the Send Events permission. Learn more about API keys here.

Create Events

Supports batch creation of events.

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.

Securityconfiguration_key or ingest_key
Request
path Parameters
datasetSlug
required
string

The dataset slug.

header Parameters
Content-Encoding
string

Included when sending events in a file. Size limitations may be addressed by compressing request bodies with gzip or zstd compression. Be sure to set the Content-Encoding to gzip or zst.

Enum: "gzip" "zst"
Example: gzip
Request Body schema:
required

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 JSON payload should have the structure:

[{ "data": { "key1": "value1", "key2": 2.0 } }, ... ]

Size limitations may be addressed by compressing request bodies with gzip or zstd compression.

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

string <binary>
Responses
200

Enqueued for processing

400

Bad Request

401

Unauthorized

403

Dropped due to administrative throttling

404

Not Found

429

Dropped due to rate limiting

post/1/batch/{datasetSlug}
Request samples
No sample
Response samples
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create an Event

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.

Securityconfiguration_key or ingest_key
Request
path Parameters
datasetSlug
required
string

The dataset slug.

header Parameters
X-Honeycomb-Event-Time
integer

The Event's timestamp. Optional. Defaults to server time.

X-Honeycomb-Samplerate
integer

Optional. Defaults to 1.

Request Body schema: application/json
required

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.

property name*
additional property
string or number or boolean [ 1 .. 2000 ] items

A collection of key-value properties that represent the Event. Honeycomb supports basic data types for the values of each Event attribute.

Limits

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

Enqueued for processing

400

Bad Request

401

Unauthorized

403

Dropped due to administrative throttling

404

Not Found

429

Dropped due to rate limiting

post/1/events/{datasetSlug}
Request samples
application/json
{
  • "method": "GET",
  • "endpoint": "/foo",
  • "shard": "users",
  • "duration_ms": 32
}
Response samples
application/json

The body is empty, or blank.

{
  • "error": "Request body should not be empty."
}
➔ Next to Environments