Pagination

Most list endpoints on the Platform API (…/api/v2.0) return results in numbered pages so large result sets stay manageable. Two query parameters control pagination:

Every page-paginated response includes a count (total matching items) plus next and previous URLs you can follow to walk the result set:

{
  "count": 412,
  "next": "https://api.surfact.com/api/v2.0/devices/?page=2&page_size=20",
  "previous": null,
  "results": [ ... ]
}

📘

Pagination is optional

If you omit these parameters, the endpoint returns the first page using the default page_size.

Example

Retrieve the first 20 cold-chain trackers in your fleet:

curl -X GET 'https://api.surfact.com/api/v2.0/devices/?page=1&page_size=20' \
  -H 'X-Auth-Token: your_token_here'

To page through every device, keep requesting the URL in the next field until it returns null.

Exception: event logs are cursor-paginated

GET /events/{event_id}/logs/ does not use page numbers. It returns a cursor-paginated envelope with only next, previous and results — there is no count, so you cannot know the total up front, and the page parameter is ignored (requesting page=1 and page=2 returns the same rows).

{
  "next": "https://api.surfact.com/api/v2.0/events/<event_id>/logs/?cursor=cD0yMDI2LTA3LTMwKzExJTNBNDklM0E1My4xOTYyNDglMkIwMCUzQTAw&page_size=2",
  "previous": null,
  "results": [ ... ]
}

To walk the log history of a temperature excursion, request the URL in next verbatim until it comes back null — the cursor value is opaque, so never construct or edit it yourself. previous is null on the first page and carries a backwards cursor from then on.

curl -X GET 'https://api.surfact.com/api/v2.0/events/<event_id>/logs/?page_size=50' \
  -H 'X-Auth-Token: your_token_here'

There is also no default page size here: omit page_size and the endpoint returns the event's entire log history in a single response with next: null.

👍

Combine with other parameters

Pagination works alongside Field Filters, Sorting, and Dynamic Fields — e.g. filter to one customer's pharma fleet, sort by label, and page through the results.