Since and Until Time Range

Many REST API queries accept the since and until parameters. These parameters allow you to gather metric data within a specific time range. Because, when included, this two parameters are required, by specifying a time range, you are encouraged to consider how much data you want to retrieve. For example, you may not want to retrieve all server requests since the beginning of time.

The since and until parameters are in UTC (Coordinated Universal Time) format:

yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

The time represented by until must be later than the time represented by since, and both must be later than the date January 1, 2013. For example:

/api/v1/requests?since=2015-11-25T22:00:00.000Z&until=2015-11-30T10:30:00.000Z

Internally, metric information is stored at precise 1-minute aggregation intervals, therefore your time-stamp parameters should be on 1-minute boundaries. Typically, the time range interval returned will exactly match the time range interval (with 1-minute boundaries) specified in the query parameters.

Any operation that accepts time range input parameters will also return, in its JSON response a timeRange element containing two long values. These values represent the Unix epoch, or the number of milliseconds that have elapsed since midnight January 1, 1970, and reflect the actual time range used internally by the system (as noted this will usually exactly match your input parameters). For example, using the query fragment just above, the JSON response will include the following element:

"timeRange" : {
    "since" : 1448488800000,
    "until" : 1448879400000
}

However, when dealing with time series data (the /timeSeries query), the time range interval returned from the REST API may not exactly match the time range specified as input, and may not start at the since value specified. This is a result of aggregation period adjustments and described in the Time Series overview.