Timeseries

Bucketed counts and values over time.

A timeseries splits a query into buckets across your time range. Each bucket contains the count (or value) for the events that fell in it, so you can see how activity changes over time.

What a timeseries returns

const signupsPerDay = await vanta.timeseries({
  filters: filter('type', 'equals', 'user.signup'),
  interval: 'day',
  time: timeRange('2024-01-01T00:00:00Z', '2024-01-14T23:59:59Z'),
})

The response is a list of buckets ordered by time:

{
  "interval": "day",
  "buckets": [
    { "timestamp": "2024-01-01T00:00:00Z", "count": 412 },
    { "timestamp": "2024-01-02T00:00:00Z", "count": 388 },
    { "timestamp": "2024-01-03T00:00:00Z", "count": 455 }
  ]
}

The timestamp in each bucket is the start of that bucket.

Choosing an interval

Intervals

The interval is one of:

• minute
• hour
• day
• week
• month

Pick an interval that matches the shape of the question:

const hourlyTraffic = await vanta.timeseries({
  filters: filter('type', 'equals', '$page'),
  interval: 'hour',
  time: timeRange('2024-01-01T00:00:00Z', '2024-01-02T23:59:59Z'),
})

UTC buckets

Buckets are aligned to UTC boundaries. A day bucket starts at 00:00 UTC, an hour bucket starts at the top of the hour. This keeps results consistent no matter who is viewing them.

Empty buckets

Buckets with zero events are typically not emitted. A quiet period shows up as a gap in the results rather than a row of zeros. Account for this when charting: gaps are expected, not missing data.