Understand Time

Timestamp

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.

Note that the end_date parameter is inclusive. We suggest that you subtract one second or millisecond from the end_date to ensure the entire interval is captured. For example, to get the entire day of February 28th, 2024:

Copy
Copied
{
    "start_date": "2024-02-28T00:00:00Z",
    "end_date": "2024-02-28T23:59:59Z"
}

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, 10minute, 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.

The restrictions for time ranges and time_resolution are the following:

  • minute and 10minute resolution < 1 day.
  • hour and hour_of_day resolution < 7 days.
  • day and weekday resolution < 31 days.
  • all other resolutions < 1 year.

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.

Retention

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