Pagination

Sensos API endpoints that return collections (such as devices, shipments, or alerts) support cursor-based pagination to enable efficient data retrieval across large result sets.

How It Works

Sensos APIs return a cursor in the response, which is used to retrieve the next page of results.

This approach is more resilient to data changes and ensures consistent results during iteration.

Request Format

To paginate through a collection, use the cursor query parameter:

GET /v1/accounts/{accountId}/<entity>?cursor=<cursor>

• If no cursor is provided, the first page of results will be returned.
• If a cursor is provided, the response will contain the next page starting from that position.
• To request the total number of items in the collection, add includeTotal=true to the query string.

Response Format

A paginated response includes a metadata object and a list of items. An example:

{
  "metadata": {
    "total": 500,
    "nextCursor": "ZXhhbXBsZS1jdXJzb3Itc3RyaW5n"
  },
  "devices": [
    { "id": "device-1", "name": "Sensor 1" },
    { "id": "device-2", "name": "Sensor 2" }
  ]
}

Fields

• metadata.total: The total number of items available (may be approximate in some APIs).
• metadata.nextCursor: A string token used to fetch the next page. If absent or null, there are no more results.

Pagination Loop Example

To iterate through results:

1. Make a GET request without a cursor to fetch the first page.
2. Read the nextCursor value from the response.
3. Continue requesting with ?cursor=<nextCursor> until no cursor is returned.