Pagination Patterns

Overview

To maintain consistency, offset pagination is recommended as the default approach. However, datasets won’t always be small, so APIs can also support cursor-based pagination as an optional alternative for handling large datasets efficiently.

Offset pagination: Default method (recommended)
Cursor-based pagination: Optional advanced method for large datasets

Offset Pagination

Offset pagination is the standard pagination method using page numbers.

Response Structure

export interface Pagination {
  /**
   * Number of results per page eg 10
   */
  resultsPerPage: number;
  /**
   * Current page number eg 1
   */
  currentPage: number;
  /**
   * Total number of pages eg 10
   */
  totalPages: number;
  /**
   * Represents the total number of results returned by current query
   */
  totalResults: number;
  /**
   * Represents the total number of items available in the database (#nofilter)
   */
  totalAvailableItems?: number;
}

Query Parameters

resultsPerPage

number

default:"10"

Control the number of results per pageMaximum recommended: 100

page

number

default:"0"

Current page (zero-indexed)Note: Page numbering starts at 0

Example Request

GET /api/@next/public/applications?page=2&resultsPerPage=20

Example Response

{
  "data": [
    {
      "applicationType": "planningPermission",
      "data": {
        "application": {
          "reference": "ABC-2024-001"
        }
      }
    }
  ],
  "pagination": {
    "resultsPerPage": 20,
    "currentPage": 2,
    "totalPages": 8,
    "totalResults": 156,
    "totalAvailableItems": 1234
  }
}

Offset Pagination Fields

resultsPerPage

number

Number of items returned in the current page

currentPage

number

Current page number (zero-indexed)

totalPages

number

Total number of pages available

totalResults

number

Total number of results matching the current query filters

totalAvailableItems

number

Total number of items in the database without any filters appliedOptional field

Cursor-Based Pagination

Cursor-based pagination is more efficient for large datasets and provides better performance when data is frequently updated.

Response Structure

export interface CursorPagination {
  /**
   * Number of results per page eg 10
   */
  resultsPerPage: number;
  /**
   * Cursor to the next page
   */
  nextCursor: string | null;
  /**
   * Cursor to the previous page
   */
  prevCursor: string | null;
  /**
   * Represents the total number of results returned by current query
   */
  totalResults: number;
  /**
   * Represents the total number of items available in the database (#nofilter)
   */
  totalAvailableItems?: number;
}

Query Parameters

resultsPerPage

number

default:"10"

Control the number of results per page

cursor

string

default:"abc123"

Cursor position for the current pageUse the nextCursor or prevCursor values from the previous response

Example Request

# First request (no cursor)
GET /api/@next/public/applications?resultsPerPage=20

# Subsequent request (with cursor)
GET /api/@next/public/applications?resultsPerPage=20&cursor=eyJpZCI6MTIzNH0=

Example Response

{
  "data": [
    {
      "applicationType": "planningPermission",
      "data": {
        "application": {
          "reference": "ABC-2024-001"
        }
      }
    }
  ],
  "pagination": {
    "resultsPerPage": 20,
    "nextCursor": "eyJpZCI6MTI1NH0=",
    "prevCursor": "eyJpZCI6MTIxNH0=",
    "totalResults": 156,
    "totalAvailableItems": 1234
  }
}

Cursor Pagination Fields

resultsPerPage

number

Number of items returned in the current response

nextCursor

string | null

Cursor for the next page of resultsWill be null if on the last page

prevCursor

string | null

Cursor for the previous page of resultsWill be null if on the first page

totalResults

number

Total number of results matching the current query filters

totalAvailableItems

number

Total number of items in the database without any filters appliedOptional field

Choosing a Pagination Method

Use Offset Pagination When:

Dataset is small to medium-sized (< 10,000 records)
Users need to jump to specific page numbers
Total page count is important for UI
Data doesn’t change frequently

Use Cursor-Based Pagination When:

Dataset is very large (> 10,000 records)
Performance is critical
Data is frequently updated
Sequential access is sufficient
Real-time feeds or infinite scroll UI

Implementation Notes

Page Indexing: Offset pagination uses zero-based indexing. The first page is page=0.

Performance Consideration: For datasets with more than 10,000 records, cursor-based pagination is strongly recommended to avoid performance degradation.

Cursor Format: Cursor values are opaque strings (typically base64 encoded). Clients should not attempt to parse or construct cursor values manually.

API Implementation

Type Reference

Overview

Response Structure

Query Parameters

Example Request

Example Response

Response Structure

Query Parameters

Example Request

Example Response

Implementation Notes

Next Steps

Filtering

Endpoints

Build docs developers (and LLMs) love

API Implementation

Type Reference

​Overview

​Offset Pagination

​Response Structure

​Query Parameters

​Example Request

​Example Response

​Offset Pagination Fields

​Cursor-Based Pagination

​Response Structure

​Query Parameters

​Example Request

​Example Response

​Cursor Pagination Fields

​Choosing a Pagination Method

​Use Offset Pagination When:

​Use Cursor-Based Pagination When:

​Implementation Notes

​Next Steps

Filtering

Endpoints

Build docs developers (and LLMs) love

Overview

Offset Pagination

Response Structure

Query Parameters

Example Request

Example Response

Offset Pagination Fields

Cursor-Based Pagination

Response Structure

Query Parameters

Example Request

Example Response

Cursor Pagination Fields

Choosing a Pagination Method

Use Offset Pagination When:

Use Cursor-Based Pagination When:

Implementation Notes

Next Steps