Pagination

Sensos API endpoints that return collections (such as devices, shipments, points of interest, or operations) support cursor-based pagination to enable consistent, high-performance data retrieval across large result sets.

How It Works

Cursor-based pagination uses an opaque token (cursor) that marks a specific position in the data stream. Rather than computing page offsets, each request fetches the next chronological batch starting immediately after the cursor.

This approach prevents duplicate or skipped items when records are inserted or modified during pagination.

Query Parameters

Parameter	Type	Default	Description
`cursor`	String	(None)	Opaque pagination cursor returned as `metadata.nextCursor` in a previous response. Omit on the first call to retrieve the first page.
`limit`	Integer	`50`	Maximum number of records to return in a single page (allowed range: `1` to `100`).
`includeTotal`	Boolean	`false`	When set to `true`, returns the total count of items matching the query in `metadata.total`.

Request Example

GET https://api.sensos.io/v1/accounts/{accountId}/shipments?limit=50&cursor={cursor}&includeTotal=true
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Accept: application/json

Response Format

Paginated responses return a top-level metadata envelope alongside an array containing the resource records.

ℹ️
Collection Array Keys:

Order & Shipment Management Service (OMS) endpoints return the collection under the generic key items (e.g. items: [...]).

Device Management Service (DMS) endpoints return the collection under the entity-specific key devices (e.g. devices: [...]).

Example Response (Shipments)

{
  "metadata": {
    "total": 348,
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA5LTE0VDA4OjMwOjAwWiIsImlkIjoiMzU3YWViYzUtNjkyZC00YjI1LTg3ZDAtZmM5ZWU3YjNhZGE5In0="
  },
  "items": [
    { 
      "id": "357aebc5-692d-4b25-87d0-fc9ee7b3ada9", 
      "name": "Cold-Chain Pharma Batch #1048", 
      "status": "InTransit" 
    }
  ]
}

Metadata Fields

metadata.nextCursor: An opaque string token to supply in the cursor query parameter of your next request. If null, empty, or missing, you have reached the final page.
metadata.total: The total count of records matching your query criteria (included when includeTotal=true is requested).

Pagination Loop Code Samples

import requests

def fetch_all_shipments(account_id: str, access_token: str):
    url = f"https://api.sensos.io/v1/accounts/{account_id}/shipments"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/json"
    }
    params = {"limit": 50}
    all_shipments = []

    while True:
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()
        data = response.json()

        # Append current page items
        items = data.get("items", [])
        all_shipments.extend(items)

        # Retrieve next cursor
        next_cursor = data.get("metadata", {}).get("nextCursor")
        if not next_cursor:
            break  # Reached last page

        params["cursor"] = next_cursor

    return all_shipments

async function fetchAllShipments(accountId: string, accessToken: string) {
  const allShipments = [];
  let cursor: string | undefined = undefined;

  do {
    const url = new URL(`https://api.sensos.io/v1/accounts/${accountId}/shipments`);
    url.searchParams.set("limit", "50");
    if (cursor) {
      url.searchParams.set("cursor", cursor);
    }

    const res = await fetch(url.toString(), {
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Accept": "application/json"
      }
    });

    if (!res.ok) {
      throw new Error(`Pagination request failed: ${res.status}`);
    }

    const data = await res.json();
    allShipments.push(...(data.items || []));
    cursor = data.metadata?.nextCursor;
  } while (cursor);

  return allShipments;
}

Updated 10 days ago

Did this page help you?