Skip to main content

Limits, versioning, and support

Rate limits and fair use​

The API does not currently enforce hard per-key request quotas. It relies on fair use, and the patterns below will keep your integration fast and reliable:

  • Match your polling rate to how often the data changes. Occupancy and sightings update at most every ~2 seconds, and polling occupancyChanges every 30 seconds with a from/nextFrom cursor is a good default. Analytics updates once a day, so a daily poll is enough.
  • Prefer webhooks for frequent changes. If you find yourself polling often to keep up, a webhook will deliver the same data with lower latency and less work on both sides.
  • Prefer fewer, larger queries. One building- or floor-scoped query is cheaper than many per-space queries, even if it fetches more than you need. Aliased queries in a single request execute sequentially, so batching by scope (floor, building) is faster and avoids timeouts.
  • Request windows and retention limits per dataset are listed in Available data.

If you have a workload in mind that sits outside these patterns (large portfolio backfills, or polling faster than every 30 seconds), reach out before you build and we will help you find the most efficient approach.

Schema stability and breaking changes​

The external GraphQL schema evolves additively: new fields, arguments, types, and enum values are added over time, and existing ones are not removed or repurposed without warning. Build clients that tolerate additions, so that an unknown field or a new enum value is ignored rather than treated as an error.

When a breaking change is unavoidable, XY Sense notifies registered API users ahead of time with a migration window.

The generated API reference always reflects the current production schema.

Getting help​

  • Integration questions or unexpected results: contact your XY Sense representative or reach us via support@xysense.com.
  • Include your query (with variables), the full response including any errors array, and a timestamp. That is usually enough for us to reproduce.
  • Feature enablement (Occupancy API, Analytics API, Webhooks) and dev-mode floors are provisioned by XY Sense, ask your representative or contact us via support@xysense.com.