Send custom data to Databox

After you’ve created your Token and your first Custom Metric it’s time to start sending your custom data to Databox.

There are three ways to send your data to Databox:

  1. Using our SDKs (recommended) or
  2. Directly from a command line.

How to send data using our SDKs
To send your custom data to Databox using our SDKs, follow these steps.

How to send data directly from a command line

Use the image below as a guideline when sending your custom data to Databox using a command line. 

curl https://push.databox.com \
-u <your_token>: \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.databox.v2+json' \
-d '{
  "data":[
    {
      "$<metric_key_id>": 420
    }
  ]
}'

  1. Replace the sample token in the second line <your_token>  with the Token you previously created
  2. Replace the <metric_key_id> with the metric key identifier that you previously defined.

Note: The metric name field is case sensitive and you can use any alphanumeric value (a-z, A-Z, 0-9, _).

Pro Tip: The dollar sign ($) before metric name is mandatory. If you’re using an SDK, this will be added automatically. This character is used to differentiate a metric from its attributes. Read more about metric attributes here

The example above will store the value 123.000 to the metric ‘$<metric_key_id>‘, located in the custom Data Source with the hash identification <your_token>.

By default, the current date and time (now) will be used to store information about sent events. If you would like to store events that happened in the past or will happen in the future, you can use the optional Date property. Learn more about Date and Time.

Pro Tip: A metric value must be purely numeric. Whole numbers can be up to 16 digits long. When storing decimal values (using the decimal separator “.”), up to 6 decimal digits are supported.

For currency values, you can attach a unit to it. Percentages can be formatted directly in Databox. For duration and relative time metrics you have to push a UNIX timestamp (epoch time) in milliseconds as the metric value and then select the ‘Duration’ or ‘Relative time’ Format.

Sending multiple metrics at once
You can also send multiple metrics at once, like so:

curl https://push.databox.com \
-u <your_token>: \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.databox.v2+json' \
-d '{
  "data":[
    {
      "$sales": 420,
      "$tax": 3.4
    }
  ]
}'

Pro Tip: If your metric is not created yet or if you used the wrong metric key identifier (i.e. ‘$sales’), the PushAPI service will create it upon first push. However, we recommend you create a metric beforehand and set the necessary parameters to avoid incorrect data presentation.

Storing multiple values with the same timestamp
In case you are storing new or multiple values on a specific (same) timestamp, every new value will be overwritten. This is the default behaviour and useful in case you’re updating a daily value multiple times per day or if you’re updating historical timestamps with updated values.

In case you are storing event values where more than one event appeared at the same time (either exact timestamp or just day), you want both values to be stored. For this, enable the setting “Handling multiple values for identical Date/Time” from the Metric definition popup. Note that this setting is available for all aggregation functions except “Latest”.

Metric Definition

If your payload has been accepted, you will receive a 200 – OK message. If you receive an error, review this Responses and errors guide.

Once you’ve successfully sent your data, it’s time to view your data in Databox.