This website uses cookies to give you the best experience on our website. Using this website means you are okay with this but you can find out more here.

Metrics Ingestion Protocol

Next, we present the ingestion protocol format and its syntax. Please be aware of the empty spaces that separate the main values.

Elements represented within brackets are optional:

metric[,tag1=value][,tag2=value] value unix_timestamp [aggregation1][,aggregation2][,aggregation_frequency]






Tags are an optional element. These are formatted as key=value with a semicolon between each key-value pair. Statful is agnostic to the tags you use, so you are free to use whatever tag and value you think that makes sense in your scenario. The following non-Unicode characters are also a viable option: (-,.,:,@,_,/).

Value represents the value that must be ingested by Statful. It is accepted as any positive or negative digital character from [0,9].

Unix Timestamp is a point in time to which your metric (value) is associated when stored. It must be represented by seconds since EPOCH (i.e., in Unix time).

Aggregation represents the function that Statful must use to aggregate the values received during a specified time interval. This element is optional, but if it is presented, then the aggregation_frequency field must also be supplied.

Aggregation Frequency represents the time interval in which Statful considers the values received before executing an aggregation function. This value is expected in positive integers with pre-defined values ranging from 10 to 300s. The full list of supported aggregations and frequencies is available here.



Example of Usage

A typical curl request looks as follows:

$ curl “https://api.statful.com/tel/v2.0/metrics" -X PUT -H “M-Api-Token: 23dh4f07-03sb-47f3-80h2-1d4434d6kgtb” -H “Content-Type: text/plain” --data-binary “test.demo.metric,client=curl,env=EU 100 $(date +%s)”




This request is sending to Statful:

  • a metric named test.demo.metric;
  • with a value of 100;
  • with the tags:
    • key: client - value: curl
    • key: env - value: EU; and
  • the current timestamp.

Aggregated Metrics


As mentioned earlier, it is possible to send aggregations in a request. Let’s say you want to send the count of data points per 10 seconds.

We can change the previous request by adding the element:

$ curl “https://api.statful.com/tel/v2.0/metrics" -X PUT -H “M-Api-Token: 23dh4f07-03sb-47f3-80h2-1d4434d6kgtb” -H “Content-Type: text/plain” --data-binary “test.demo.metric,client=curl,env=EU 100 $(date +%s) count,10“


Feel free to verify the syntax of your own request at any time in our validator below.



Validate Metric








AggregationsMetric Types