Skip to main content

Event Data Format

Please read general information about Tracking Api first.

EventBunker supports a flexible JSON format as event data structure. Mandatory fields are event_name in your json data and a valid write api key.

In principal we support JSON types; string, number, float, null, boolean, string array, number array, bool array and nested object contaning same types mentioned earlier in object fields. Arrays that have mixed string and number values are not supported. Objects with another nested object inside it are also not supported for now.

EventBunker is using JSON Schema Validation, specifically this version, for incoming json parsing and validation, so you will get an error from validator if your request is not valid against our schema.

You will find our JSON Schema here for your convenience :


You do not have to know about JSON schema validation to use EventBunker apis, we will provide easy to understand, plain English validation error message responses from api.

Pre-defined Event Data Fields

In additional to reserved fields, which you can not overwrite, we have also defined field names for common event analytics use-cases. All of these fields are optional except event_name

Field NameRequiredTypeDescription
event_nameYesstringName of Event. Max 2000 unique names. Only letters[a-z][A-Z], numbers, dot(.) or underscore(_) or hyphen(-)
timestampNostringDate of event in the format that must be parsable by JS Date format link Timezone will be converted to UTC in database. Examples; "2021-10-10T14:48:00", "2021-10-10T14:48:00.000", "2021-10-10T14:48:00.000+09:00"
customer_identifierNostringYour customer's identifier, can be any string value. You can use it to write and query data for single user. Please click for usage detail
metric_nameNostringIf you also want to use EventBunker as a timeseries database. Please set event_name to metric or similar fixed value for this. Or you can use event_name as main category name for your metric_name You will have to provide a event_name value to query metrics with a metric_name value
metric_valueNofloatFloat value for metric_name. Will be used for sum, max, min, avg, etc.. type of aggregation

There is an additional feature in write api keys when a customer_identifier attached to it, read more at How to Use Api Keys

All Other Possible Field Types

Like mentioned above, EventBunker works with many kind of JSON types. Here we will list all of the types we support as JSON can be pretty complex if you use nested data a lot. Refer here for JSON types.

Field names should be valid string. Only letters[a-z][A-Z], numbers, dot(.) or underscore(_) or hyphen(-).

Field TypeDescriptionExample
stringAny json string value{"my_field": "my_string_value_is_the_best_"}
numberAny json number value, int and float{"my_number_field": 123.45}
nullJust null json type{"my_null_field": null}
booleanA json bool value{"my_bool_field": true}
string arrayA json array with string elements{"my_string_array": ["cat", "dog"]}
number arrayA json array with number elements{"my_number_array": [123, 124, 125.88]}
boolean arrayA json array with boolean elements{"my_bool_array": [true, false, false]}
objectA json object, can contains any possible types listed above{"my_object": { "a_string_field": "somevalue", "an_array_field": [true, false, false ], "and_number_field": 123.45 } }
  • 2-level nested object, which is a nested object inside a nested object, is not supported at this moment.
  • An array containing objects is also not supported because it would be hard to query on this data type. If you absolutely need one of not supported types, please contact us.

Reserved Fields and Descriptions

Reserved field names are listed in table below, if your request data contains this fields then you will get a json schema validation error. All of these fields are saved in our datastore, so you can leverage any field in Query Api

Field NameReservedTypeDescription
_eb_timestampYesnumberUTC timestamp when the event received by api
_eb_unique_req_idYesstringRandom and unique id, given by api for each request
_eb_organization_idYesstringYour Account Id
_eb_project_idYesstringYour Project Id
_eb_write_keyYesstringWrite key which is used in this api call
_eb_raw_jsonYesstringRaw JSON request body
_eb_ipYesstringIP address which POST request has been sent
_eb_countryYesstringCountry information from IP2Location
_eb_cityYesstringCity information from IP2Location
_eb_metro_codeYesstringUS Metro code information from IP2Location
_eb_latitudeYesfloatLatitude information from IP2Location
_eb_longitudeYesfloatLongitude information from IP2Location
_eb_timezoneYesstringTimezone information from IP2Location
_eb_http_referrerYesstringHttp referer header, if exists
_eb_http_originYesstringHttp origin header, if exists
_eb_utm_sourceYesstringHttp Query utm_source parameter, if exists
_eb_utm_mediumYesstringHttp Query utm_medium parameter, if exists
_eb_utm_campaignYesstringHttp Query utm_campaign parameter, if exists
_eb_browserYesstringRequest browser name, if user-agent header is valid
_eb_device_typeYesstringRequest device info, if user-agent header is valid
_eb_device_vendorYesstringRequest device vendor info, if user-agent header is valid
_eb_operating_systemYesstringRequest OS, if user-agent header is valid