Device history

Pagination

The device history endpoint is paginated using cursor-based pagination. The response contains either a next or prev URL (depending on the direction you paginate) that you can use to navigate through the pages of data. Each page contains a maximum of n data points where n might differ by device category or integration.

The direction of pagination is determined by if you send in a since parameter (forward pagination, using the next link) or an until parameter (backward pagination, using the prev link).

The effectiveStart and effectiveEnd properties in the query object in the device history response tells you if the API had to do any adjusting of the date/time range. It describes the effective query window being used and might not necessarily align exactly with either since nor until due to said clamping.

Minutes, seconds and milliseconds are always truncated away from any date/time you send in, but it's not guaranteed that the API will always return data aligned to the resolution you requested. For example, if you request hourly data, you might get data points that are not aligned to the top of the hour. Usually this is not the case, but you should not rely on it since we return the data as it is stored in our systems, unaltered after the initial processing.

History resolution

The device history endpoint supports different resolutions for the historical data, depending on the device category and integration. The available resolutions are:

• quarterHour (15 minutes)
• hour
• day
• month

Not all resolutions are available for all device categories and integrations (and some do not even support history at all). The available resolutions for a specific device can be found in the response from the get devices and get device endpoints. Look at the property supportedHistory in the device object. If this array is empty, history is not supported, and you should not attempt to call the device history endpoint for that device because it will only result in an error.

The maxRetentionDays property in the device object tells you how far back in time you can go when fetching historical data. This is the maximum retention period available for one or more resolutions available for that device. It is not guaranteed that all resolutions are available for the full retention period. For example, a device might have hourly data available for the full retention period, but only daily data for the last 31 days.

Use cases and guidance

The device history endpoint is meant to cover the following use cases:

• Backfilling historical data up to now, usually performed once upon starting to use the API; either by sending in a near timestamp/instant in time in the past as the since parameter, and sequentially stepping backwards, page by page, by using the prev cursor link in the ensuing responses, or by sending in a timestamp/instant in time from before you paired the device (you can just pick any instant in time a long time ago), in which case we will clamp this to the earliest data record truncated to the given resolution, and sequentially step forwards by following the next cursor link in the ensuing responses.
• Periodically ingesting the growing tail of new data by one the following mechanisms:
  1. When receiving the response for a fetch, also store/bookkeep the next cursor link, and when it's time to perform the next fetch, just follow that link and keep following any subsequent next cursor links, if available. This is the recommended way.
  2. When it's time to do a new fetch, look at the last timestamp you have stored and send in that as the since parameter and keep following the next cursor link if available.

This means you should store device data locally. The data is immutable and will not change after the fact, but gaps could (rarely) be filled in for certain device categories, in which case you could use either method above and stop following the cursor when you have filled your gaps.

In an effort to try to make the API as simple as possible to use, while still being flexible enough to cover the main use cases, by design, there is no way to query for an arbitrary slice of time series data, nor is there a way to specify a page size, also due in part to the need to retain control over the windowing functions to ensure clients keep their requests small and the API stays performant for everyone.

Since you may have to do multiple requests to retrieve all the data you need, it's important to implement some retry logic in your client, in case of transient errors. The API is designed to be highly available, but network issues and other transient problems may occur from time to time. See Retry & backoff.