How the request limit works, and how to keep a full or incremental sync well inside it.
The limit
The platform accepts up to 960 requests per minute from each source IP address, counted across all endpoints together. A few sign-in and OAuth token endpoints have lower limits.
- The limit is per IP address, not per API key. Every request sent from the same IP counts toward it, so scripts and jobs that leave your network through one shared egress IP share one budget.
- The count runs in fixed one-minute windows and starts again from zero when the next minute begins.
- A request over the limit gets HTTP
429with the body{ "error": "Too many requests" }. The response has noRetry-Afterheader.
Handling a 429Stop sending, wait until the next minute starts, then retry the request. Spread scheduled jobs over time instead of starting them all at once.
Full sync: use the list endpoints
Read whole collections from the list endpoints, page by page (see Pagination), instead of calling the single-item endpoint once per item.
| Data | List endpoint | Max per_page | Notes |
|---|---|---|---|
| Devices | Get Devices | 100 | Each item has the same fields as Get Device. The one exception: custom_parameters on Edge devices is returned only by Get Device. |
| Spaces | Get Spaces | 100 | Each item has the same fields as the single-space response, plus path. |
| Models | Get Models | 100 | The model's commands are returned only by Get Model. |
At 100 devices per page, a fleet of 10,000 devices takes 100 requests.
Devices can shift between pagesGet Devices returns the newest devices first. A device added while you are paging pushes the rest down by one, so the same device can appear on two pages. De-duplicate by device
id.
Incremental sync: read new state changes and incidents
After the first full sync, read new state changes and new incidents for all devices in one call with a time window, instead of polling each device. Renames, moves and other device edits do not appear here; pick those up with a periodic full sync.
| Endpoint | Window parameters | Returns | Max per_page |
|---|---|---|---|
| Get Histories | from, to (Unix time, seconds). The window can be at most 31 days. Default: the last 7 days. | Device state changes (online, offline, and so on) in the window. | 1000 |
| Get Incidents | from, to (Unix time, seconds). Default: the last 7 days. | Incidents created in the window. | 500 |
Both endpoints are paginated and return the newest items first. Set from to the end of your previous run so consecutive runs do not leave gaps, and set both from and to explicitly, keeping them the same on every page. If to is left out, it defaults to the time of each request, so new rows shift the pages while you read them.
Incidents in the windowGet Incidents filters on when an incident was created. An incident created before the window and closed inside it is not returned, so re-read open incidents to catch closures. Incidents suppressed by scheduled maintenance are left out unless you pass
include_suppressed=true.
Commands
Commands are sent one device per request: Send Command targets a single device_id. Sending a command to 500 devices takes 500 requests, so pace large rollouts across several minutes.
Planning large scheduled exports
If you plan a large or frequent scheduled export, contact [email protected] before you start.
