The Honeycomb API supports two endpoints—one for Events, the standard unit of data in Honeycomb, and one for Markers, a supplementary way to mark specific points in time across datasets. All requests should be made via HTTPS to api.honeycomb.io
.
We accept individual events as an HTTP POST request:
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”).
The Team Write Key, Sample Rate, and Timestamp are all specified as HTTP headers.
X-Honeycomb-Team
(required)X-Honeycomb-Event-Time
(optional, defaults to the time the server receives the event) Must be in RFC3339 format (eg YYYY-MM-DDTHH:MM:SS.ssssZ0000).X-Honeycomb-Samplerate
(optional, defaults to 1)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:
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.
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
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!)
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 |
Status Code | Body | Meaning |
---|---|---|
400 | unknown Team 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 write 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! |
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 Write 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.
Markers are for indicating points in time on your graphs where interesting things happen, such as deploys or outages. You can list, create, update, and delete markers.
All marker endpoints operate on a dataset and use the Team Write Key to authenticate.
Marker objects have the following assignable fields. All fields are optional, and may be modified at any time.
start_time
: Indicates the time the marker should be placed. If missing, defaults to the time the request arrives at the API. Expressed in Unix Time, aka seconds since the epochend_time
: not yet implemented on graphs, but will allow you to show a marker happening over a time range (such as a 5 minute deploy). Expressed in Unix Time, aka seconds since the epochmessage
: a string describing this specific marker. This string will appear above the marker line on a graphtype
: a string grouping similar markers, eg ‘deploys’. All markers of the same type will appear in the same color on the graphurl
: a target for the marker. If you click on the marker text, it will take you to this URL. For a deploy, it might be a link to the build system showing the build log for the version that was deployedWhen a marker is created or updated, the following fields are assigned. They may not be modified.
id
: The marker ID is a 6 character hexadecimal string and is assigned on marker creationcreated_at
: The time the marker was createdupdated_at
: The time of the most recent modification to the marker. It is updated every time the marker is changed.color
: You can assign a color to a marker type in the Dataset Advanced settings page in the UI. The color field will be populated when you list events.The Team Write Key is the only header accepted for markers. It is required.
Markers are created by sending a POST request to /1/markers/<DATASET_NAME>
The Marker body should be a JSON encoded object including as many of the marker fields as desired. ID may not be set during creation.
When a marker is successfully created, the API will respond with HTTP status 200 and will return a JSON object representing that marker.
An example, creating a deploy marker on the TestViaCurl
dataset:
curl https://api.honeycomb.io/1/markers/TestViaCurl -X POST \
-H "X-Honeycomb-Team: WRITEKEY" \
-d '{"message":"backend deploy #123", "type":"deploy", "start_time":1471040808}'
# {"created_at":"2016-08-13T05:39:42Z","updated_at":"2016-08-13T05:39:42Z","start_time":1471040808,"message":"backend deploy #123","type":"deploy","id":"d1c84ec0"}
Any of the modifiable fields in a marker can be updated by sending a PUT request to /1/markers/<dataset>/<marker_id>
.
The PUT request should have as its body a JSON object containing all the user-settable fields for this marker, including any updated values. If you do not include an existing field in the payload, it will be erased.
When a marker has been successfully updated, the API returns code 200 and the updated marker as the body of the response.
As an example, this curl request will change the start time of the marker created above:
curl https://api.honeycomb.io/1/markers/TestViaCurl/d1c84ec0 -X PUT \
-H "X-Honeycomb-Team: WRITEKEY" \
-d '{"message":"backend deploy #123", "type":"deploy", "start_time":1471067108}'
# {"created_at":"2016-08-13T05:39:42Z","updated_at":"2016-08-13T05:39:42Z","start_time":1471067108,"message":"backend deploy #123","type":"deploy","id":"d1c84ec0"}
Markers may be deleted by sending a DELETE request to /1/markers/<dataset>/<marker_id>
.
The body of the DELETE request should be empty.
When the marker has been successfully deleted, the API will respond with 200 and the deleted marker in the body of the response.
As an example, this curl request will delete the marker we created and modified above:
curl https://api.honeycomb.io/1/markers/TestViaCurl/d1c84ec0 -X DELETE \
-H "X-Honeycomb-Team: WRITEKEY"
# {"created_at":"2016-08-13T05:39:42Z","updated_at":"2016-08-13T05:39:42Z","start_time":1471067108,"message":"backend deploy #123","type":"deploy","id":"d1c84ec0"}
All the markers in a dataset may be retrieved by sending a GET request to /1/markers/<DATASET_NAME>
The response will be HTTP 200 and a JSON list of marker objects.