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:
An empty result means there werenoavailability 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:
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 revealsonly 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.
Hi, @John-K. Can you clarify if this shows every availability (status) change during the given time frame? For example, if a device were connected from 12:01AM to 9AM, then disconnected between 9AM and 3PM, then connected again from 3PM to 7PM, and finally disconnected for the remainder of the day... what would this endpoint tell us about the device?
I love it!!! Thanks @John-K. Since this is an org-level call, might this be a precursor to being able to get all events at the org-level without having to make network-level calls? I ask because we have customers with thousands of networks where it's rate-limit prohibitive to use the network-level events endpoints.
Hi, @John-K. This is the one I have my eye on, but it's expensive to make on a per-network call if you have thousands of networks. However, If I could make per-org calls every 5-10 minutes to get these in bulk they'd be super valuable.
However, I suspect that it these uber-large orgs we might have to do lots of paging if it's limited to 1000 per call. I'll DM you with the customer-specific info, as there are two extremely large global Meraki Orgs that I have in mind for this.