# Timeseries

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

## Example

### Request params

```json
{
    "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
```json
{
    "interval": "1d",
    "range_timezone": "America/Denver",
    "effective_from": "2024-04-08T00:00:00.000-06:00",
    "effective_to": "2024-04-25T23:59:59.999-06:00",
    "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.
* First bucket includes `from` timestamp.

## 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](https://docs.mpc.placewise.com/doc-343952#timezones)