Timeline

By default, all endpoints return the latest data; however, sometimes it is useful to see how the data changes over time.

This is achieved with the special groupBy value timestamp.

Grouping by timestamp

When grouping by timestamp, each entry in the resulting data will have a timestamp property.
Unless you provide filters over the timestamp, you'll see the entire history of the desired data.

📘

Note that if you chose to see a share calculation, its value is relative to the specific timestamp and it is not a global value.

Syntax

?groupBy=timestamp

Limitation

Filtering over timestamp is only possible when also grouping by it. Failing to do so will result in an error.

Example

In the following example you will see the difference that groupBy=timestamp makes.

First, let's see what happens without it if we want to see the average risk of devices in the manufacturing industry:

/api/v1/device/_search?industry=Manufacturing&groupBy=industry&calculate=avgRisk

[
    {
        "industry": "Manufacturing",
        "avgRisk": 4
    }
]

Now let's see what happens if we also add the groupBy=timestamp:

/api/v1/device/_search?industry=Manufacturing&groupBy=industry&groupBy=timestamp&calculate=avgRisk

[
    {
        "industry": "Manufacturing",
        "timestamp": "2022-11-01 00:00:00",
        "avgRisk": 4
    },
    {
        "industry": "Manufacturing",
        "timestamp": "2022-10-01 00:00:00",
        "avgRisk": 3
    },
    {
        "industry": "Manufacturing",
        "timestamp": "2022-09-01 00:00:00",
        "avgRisk": 4
    },
    ...
]