Timeseries

Timeseries is a format which is returned for historical timeseries data.

Example

Request params

{
    "report": "member_balance",
    "filter": null,
    "aggregate_by": "consents",
    "interval": "auto",
    "from": "2024-04-08T00:00:00.000-06:00",
    "to": "2024-04-25T00:00:00.000-06:00"
}

Response

{
    "interval": "1d",
    "range_timezone": "America/Denver",
    "time_buckets": [
        "2024-04-08T00:00:00.000-06:00",
        "2024-04-09T00:00:00.000-06:00",
        "2024-04-11T00:00:00.000-06:00",
        "2024-04-22T00:00:00.000-06:00",
        "2024-04-23T00:00:00.000-06:00",
        "2024-04-24T00:00:00.000-06:00",
        "2024-04-25T00:00:00.000-06:00"
    ],
    "series": [
        {
            "label": {
                "type": "out"
            },
            "values": [2,2,1,1,null,1,5]
        },
        {
            "label": {
                "type": "in"
            },
            "values": [null,4,300,2,1,null,11]
        }
    ],
    "data_points": 11,
    "result_type": "timeseries"
}

Intervals

Timeseries data is grouped in time buckets.

Each time bucket spans over specified interval

Each interval can have different retention times

Each report can use different intervals

Report handles 5m, 1h, 1d, 1w and 1mo intervals unless it's stated differently in Metadata endpoint.

Interval	Time bucket interval	Retention time
5m	5 minutes	14 days
1h	1 hour	6 months
1d	1 day	2 years
1w	1 week	forever*
1mo	1 month	forever*

`interval` request param

In order to specify the interval, you need to pass interval request parameter.
You can use specific interval (like 1d) or default - auto.

auto automatically chooses interval based on logic:

if to - from difference is less or equal to 12 hours then 5m

if to - from difference is less or equal to 3 days then 1h

else 1d

Time buckets

Time buckets are aligned to "full" time given by the interval. For example, when using 5m interval: 11:00:00, 11:05:00, 11:10:00, etc.

Time buckets are provided in ascending order

When there is no value for given time bucket, then it won't be returned.

Series

Single series consists of:

label - an object which describes the series

values - array of numbers. Each number is a value in the corresponding time bucket.

timezone (optional) - see Timezones handling

If there is no data in the time bucket for given series then the value will be null.

Query limits

Time points (number of time buckets)

Single query can include at most 150 time points.

For example:

when querying the data using 1d interval, number of days between from and to parameters must be less or equal to 150

when querying the data using 5m interval, number of 5m buckets between from and to must be less or equal to 150

Trying to fetch more than 150 time points will return 422 HTTP error.

If you need more time points, you need to implement iteration using from and to parameters yourself.

Data points

Single query can include at most 1000 data points.

Trying to fetch more than 1000 data points will not return HTTP error. Returned data will be just limited to 1000 data points. You can see how many data points were returned by the query via data_points response field.

In order to lower down number of data points, you need to use filter or from/to params to scope down the query.

What is a data point?

Data point is a single value point except default null values.

For example, if the query returns 3 series in which:

first have 10 non null values

second have 5 non null values

third have 15 non null values

Then the number of data points is 10+5+15 = 30

Note that there is no possibility to break 1000 data points limit unless your query returns more than 6 series.

Timezones handling

See Introduction#Timezones

Example#

Request params#

Response#

Intervals#

interval request param#

Time buckets#

Series#

Query limits#

Time points (number of time buckets)#

Data points#

What is a data point?#

Timezones handling#