Pagination

API version V5 is available now. All versions less than V5 will be shut off on March 16, 2015.

API Limits

In version 3 we introduced API Rate Limits, which took effect in two ways. For every request there is a limit for total number of requests that can be made in one hour. For log detail and server data requests there is a limit to the amount of data that can be retrieved in one hour.

With version 4 we expand upon the limit concept and introduce multiple forms of pagination: offset and cursor-based.

Offset Pagination

We’ve modified the existing structure of all the listing API calls to provide additional information and give users the ability to choose a small subset of their objects. Below you will find the additional parameters accepted and the new structure of the response. In the JSON response if there is no previous or next page then they will not exist in the ‘paging’ dictionary value. It is important to note that the current_page value will always be the index so the starting page is at 0 instead of 1. This means that the last page will be total_pages – 1.

Parameters

  • limit (integer) (default: 2500, max: 2500) – the maximum number of objects in a single page
  • page (integer) (default: 0) – the page number requested with index starting at 0. Throws 400 error if page requested is out of bounds.

JSON Response

{
            "request": {
                "limit" : USER_DEFINED or MAX_LIMIT,
                "page": USER_DEFINED or 0,
                Any additional request parameters
            },
            "data": [
                LIST_OF_OBJECTS
            ],
            "paging": {
                "total_items": total number of objects,
                "total_pages": total pages based on the limit size requested,
                "current_page": CURRENT_PAGE,
                "next_page": CURRENT_PAGE+1 or UNDEFINED,
                "next_page_url": URL of next page or UNDEFINED,
                "prev_page": CURRENT_PAGE-1 or UNDEFINED,
                "prev_page_url": URL of prev page or UNDEFINED,
            },
        }

Cursor-Based Pagination

This pagination applies to any time-series request. If the amount of data in bytes exceeds 1 MB or the time length requested is too large then the API request will be broken up. We will return a subset of the data while returning a cursor URL of where the user last left off in order to allow him/her to retrieve the rest of the data. Once the end of the data is reached then next_page_url will not exist in the paging dictionary value.

Data Size Limits
For any time-series request the maximum data size that you can retrieve is 1MB. Most summaries are only about 300 bytes so most users will uneffected. Raw process data and log messages, however, tend to be much larger in their size but that is highly dependent on user configuration.

Time Size Limits
Time size limits are dependent on the time step of the summary. Refer to the list below for details:

  • For minutes summaries – limit is set to 1440
  • For hour summaries – limit is set to 730
  • For day summaries – limit is set to 31

JSON Response

{
            "request": {
                Any additional request parameters
            },
            "data": [
                LIST_OF_TIME_SERIES_DATA
            ],
            "paging": {
                "next_page_url": URL of next page or UNDEFINED,
            },
        }