Understand Time


All timestamps sent to the API must be formatted as strings according to the ISO 8601 standard for UTC timestamps. The API will return all timestamps in the same UTC format.

Most programming platforms have built-in utilities to convert between local time and UTC.

Time Range

The minimum time range between start_date and end-date is 1 minute. If the query passes a start/end date of less than 1 minute, Density truncates date ranges to the minute. For example, if the start_date is 9:30:45 and end_date is 9:31:02, the date range would be truncated to 9:30:00 - 9:31:00.

Time Resolution

time_resolution is an optional parameter. You can specify time_resolution in your query by "hour", "day", "week", "month", "year", "weekday", "hourofday", or "total". The default is “total” when unspecified.

The lowest time_resolution is enforced by the time range of the query. For example, by minute is only available for time range < than 1 day. The best practice is to use short time range for low-time resolution queries because the size of the response can be large. For example:

  • For 1-minute resolution, query 1 hour, instead of 1 day of data.
  • for 1-hour resolution, query 1 day, instead of 1 week of data.

If you use time_resolution in your request body (other than total), the resulting response time Timestamp represents the starting time of the time interval.


Time range and resolution also have retention implications. See details in this help article for the time_resolution and retention relationship.

Time filters

Time Zone, Working Hour, and Working Days are defined in the Density portal Administration page. The Building-level setting overwrites the Organization-level settings.

The API can return all the data including from non-working days or hours if the query parameter specifies the time range (E.g. 6/16/2022 6 am - 7 am).

For aggregated data (e.g. week of 6/14 - 6/21), the time filters are applied to the data.