Skip to main content

AXIS Data Insights API usage guidelines

This guide explains key behaviors of the AXIS Data Insights API and offers recommendations for fetching its data. For information about AXIS Data Insights, see the AXIS Data Insights manual.

Data resolution and update behavior​

The API returns measurements at 15-minute or 60-minute resolution. The 60-minute values roll up the underlying 15-minute buckets. The API updates the current bucket every minute. Polling more often doesn't give you finer-grained data. You only get newer values for the current bucket.

A bucket stays open while it accumulates measurements for its period and closes when that period ends. You can tell whether a bucket is open or closed from the response. It's closed if the elapsed time between its from and to values equals the requested interval (15 or 60 minutes). Otherwise, the bucket is open, and its values are provisional. Values for the current open bucket can change until it closes. If you poll while a bucket is open, overwrite the values you previously stored for it. Don't add successive responses together. Doing so can count the same data more than once.

If you only need final values, request data up to the latest fully closed boundary for your chosen interval. Poll at approximately that same interval.

Time ranges​

The from and to parameters accept either:

  • Naive date and time values, which are interpreted as local wall-clock time at each site.
  • UTC date and time values with a Z suffix, which represent one instant across all sites.

Use the same format for both parameters. For programmatic integrations, use UTC values by default. Naive values are useful when a report must use the same local hours at every site, such as 09:00 to 17:00.

Polling strategy​

For regular ingestion, use a forward-only polling loop:

  1. Track the to value from the last successfully fetched response.
  2. Request data using that value as from, and the current time as to.
  3. Upsert the returned measurements using a key that includes the site, device, measurement type, bucket start time, and source.
  4. Only update the tracked to value after processing the response successfully.

Upserting makes retries and small overlaps safe. Poll every minute when you need the freshest available values. If you only need closed buckets, poll less often as described in Data resolution and update behavior.

Concurrency limits​

For the cloud API, send one request at a time for each API key and organization ID pair. The API queues additional requests until the current request completes and drops any that time out while waiting. Wait for a response before sending the next request.

Late-arriving measurements​

If a device temporarily loses its connection, measurements from that period may arrive after the period ends. The API may then return updated values for past buckets.

Don't repeatedly fetch large historical ranges. Instead, re-fetch a limited range of recent data at regular intervals or when you know a device was offline or your integration detects missing data.