This endpoint returns the time-stamped availability change events that occurred for the organization's devices in the requested timespan, and is intended to be a hyper-efficient means of monitoring device availabilities. You can get started by calling:
GET /organizations/:organizationId/devices/availabilities/changeHistory
An empty result means there were no availability changes for any device in that organization for that timespan.
Default timespan is 1 day; maximum timespan is 14 days. Aside from the standard t0/t1/timespan controls, other filters include:
productTypes[]
networkIds[]
serials[]
statuses[]
Here's an example response, indicating that a single MV device changed from online > offline status, and subsequently changed back online status about 2 days later. It also indicates that no other device in the organization had any change in availability for that timespan.
This can be used for many purposes, such as:
- Finding historical availability information for one or more devices. Has a device changed status around the time the user originally reported an issue? Now you can look back (up to 14 days) and find out!
- If you monitor device availability via API, then for stable networks, using this history endpoint will be far more efficient than polling availability (or statuses) for every device in the organization. Instead of gathering a ton of "online" data points, you can instead focus on the changes that might evidence an issue (or a resolution). The endpoint reveals only the changes during the timespan, so if you get an empty response, that means there were no changes.
In other words, if you have gathered a complete picture as of a given timespan via polling an org's devices' availabilities (either via the /availabilities or /statuses endpoints), then you can subsequently switch to polling for changes from that snapshot, and get the differential data with which to update your locally cached information. - Building the "Connectivity" bars the dashboard offers under Organization > Overview > Devices tab
- Sleeping easier at night, I hope!
Thanks to our Early API Access community for your valuable feedback during beta! This endpoint is now GA and we look forward to hearing how this new endpoint helps to streamline your workflows.
