Specifying Time Ranges for API Requests

When making API requests, you can specify time ranges to retrieve data for a certain period. This section explains how to use the window, from, and to parameters to define these ranges. The data output from these requests is sorted chronologically.

Using the window Parameter

For endpoints supporting time range queries, the window parameter lets you specify a duration in the past from which to fetch data, up to the time of the request. Format this parameter as a number followed by an optional unit of time (s for seconds, m for minutes, h for hours, d for days, w for weeks). If no unit is specified, the default is seconds.

  • Format: window=[0-9]+[smhdw]?
  • Examples:
    • window=10d retrieves data from the past 10 days.
    • window=12h fetches data from the past 12 hours.
    • window=1200 (or window=1200s) gets data from the past 1200 seconds.

Using from and to Parameters

To specify an exact date and time range for your data, use the from parameter and optionally the to parameter. If to is omitted, the API assumes the current time. Dates and times must follow the ISO 8601 format (YYYY-MM-DDTHH:MM:SS), with the date and time separated by a T. The timezone is UTC.

  • Format:
    • Single date/time: from=YYYY-MM-DDTHH:MM:SS
    • Date/time range: from=YYYY-MM-DDTHH:MM:SS&to=YYYY-MM-DDTHH:MM:SS
  • Example: from=2012-01-01T00:00:00&to=2012-01-02T00:00:00

Important Considerations

  • The window and from/to parameters are mutually exclusive. Specifying both in a single request results in a 400 error.
  • Omitting from while specifying to also leads to a 400 error.
  • On endpoints requiring a roundId (a timestamp marking the start of a data collection round), this ID should be the epoch time in seconds at the start of a round. The roundId value is precisely divisible by the test's frequency, which is also specified in seconds. For example**, if a round starts at 2015-06-30 16:00:00 UTC, the roundId would be 1435680000. For a test with a 5-minute interval, subsequent roundId values would be 1435680300, 1435680600, 1435680900, and so on.

For information on error codes and responses, see Response status codes.