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, hour_of_day, minute, or total. The default is total when unspecified.

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

  • For minute resolution, query 1 hour, instead of 1 day of data.
  • for hourly 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.