Time Ranges

Every analytics query runs against a UTC time range.

Analytics answers questions about a period of time, so every query takes a time range. The range is a start and an end, expressed in ISO 8601.

The time field

Build a range with the timeRange(start, end) helper and pass it to any analytics method:

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

Time is required for analytics queries: counts and buckets have no meaning without a window.

ISO 8601 and UTC

Timestamps are ISO 8601 datetimes in UTC, always ending in Z:

timeRange('2024-01-01T00:00:00.000Z', '2024-12-31T23:59:59.000Z')

Provide UTC explicitly. The trailing Z is not optional, and naive timestamps without a timezone do not satisfy the requirement.

Inclusive bounds

For list-event queries, the bounds are inclusive: both start and end are included in the result. A range starting at 00:00 and ending at 23:59:59 covers the whole day.

Relative ranges

For rolling windows, compute the timestamps on the client:

const now = new Date()
const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)

const count = await vanta.count({
  filters: filter('type', 'equals', 'user.signup'),
  time: timeRange(sevenDaysAgo.toISOString(), now.toISOString()),
})

UTC bucketing

For count and timeseries queries, the range is bucketed in UTC. Buckets align to UTC boundaries, so results are consistent regardless of the viewer's timezone. See Timeseries for interval details.

const result = await vanta.count({
  filters: filter('type', 'equals', 'user.signup'),
  time: timeRange(
    '2026-09-09T16:25:58.935Z',
    '2026-09-10T16:25:58.935Z',
  ),
})