Skip to main content

Pagination

List endpoints return results one page at a time. From API version 3.7.0 you page with a cursor: pass the next_cursor from one page to get the next, until has_more is false.


Which endpoints are paginated​

  • GET /agreements
  • GET /files
  • GET /themes

These return result_type: "paginated_list" with a pagination object next to data.


Cursor pagination​

API clients on version 3.7.0 or later get this pagination object:

Cursor pagination
{
    "version": "1.0",
    "resource_type": "agreement",
    "result_type": "paginated_list",
    "pagination": {
        "limit": 50,
        "has_more": true,
        "next_cursor": "2.d.mvlezzly.u9REw7ZiC5jq.cmvlezzlx00033lzeo4goe9sg"
    },
    "data": [ ... ]
}
  • limit: The number of items you asked for. If the page has items but fewer than you asked for, it's the number on the page.
  • has_more: Whether there are more items after this page.
  • next_cursor: The value to send as cursor to get the next page. null when there are no more items.

There are no totals. If you need a count, page through the list.


Paging through a list​

  1. Request the first page without cursor. Set limit (default 50), order_by, and any filters you need.
  2. If has_more is true, send the same request again with cursor set to next_cursor.
  3. Repeat until has_more is false.
First page
GET /agreements?limit=100&status=pending
Next page
GET /agreements?limit=100&status=pending&cursor=2.d.mvlezzly.u9REw7ZiC5jq.cmvlezzlx00033lzeo4goe9sg

Rules for cursors​

  • Keep the query the same. A cursor belongs to the order_by and filters it was created with. Sending it with a different order_by or different filters returns a 400.
  • Treat the cursor as opaque. Pass it back exactly as you got it. Don't build or edit one yourself; an invalid cursor returns a 400.
  • Don't send page. On version 3.7.0 and later, a request with page returns a 400.

Offset pagination on older clients​

API clients older than 3.7.0 keep paging with page and get totals in the response:

Offset pagination
{
    "pagination": {
        "limit": 50,
        "page": 1,
        "total_results": 250,
        "total_pages": 5
    }
}

cursor is not available to these clients.


Requirements​

Cursor pagination requires API client version 3.7.0. Upgrade your client from the API client settings on zigned.se by clicking "Upgrade".