Pagination

Common Ground APIs use a page-based pagination system that allows you to efficiently navigate through large datasets. Both the Admin API and Client API implement consistent pagination patterns, though individual queries may have different input structures.

Overview

Pagination in Common Ground provides:

• Simple page navigation: Request specific pages by number
• Flexible page sizes: Control how many items are returned per page
• Sorting support: Sort results as part of the pagination request
• Complete metadata: Get information about total pages, item counts, and whether more pages exist

Core Pagination Types

PaginationInput

Most paginated queries accept a PaginationInput parameter to control pagination:

input PaginationInput {
  page: Int      # Page number (1-indexed, defaults to 1)
  limit: Int     # Items per page
  sort: String   # Field name to sort by
  order: Int     # Sort order: 1 for ascending, -1 for descending
}

Pagination

The Pagination type is returned with paginated results:

type Pagination {
  page: Int!        # Current page number
  pages: Int!       # Total number of pages
  limit: Int        # Items per page
  count: Int        # Total count of items across all pages
  hasMore: Boolean  # Whether there are more pages available
  sort: String      # Current sort field (if sorting is applied)
  order: Int        # Current sort order (if sorting is applied)
}

Query-Specific Pagination Patterns

Different queries may use different pagination approaches. Always check the API reference documentation for each query to understand:

• What input parameters the query accepts
• Whether it uses PaginationInput or a different structure
• What additional parameters (like filters) are required or available

Standard Pattern

Many queries follow the standard pattern with PaginationInput:

query GetItems($pagination: PaginationInput) {
  items(pagination: $pagination) {
    items {
      # Your fields here
    }
    pagination {
      page
      pages
      limit
      count
      hasMore
    }
  }
}

Queries with Additional Inputs

Some queries combine pagination with other input types. For example, inventory queries may use both filters and pagination:

query GetInventoryItems(
  $filters: InventoryFiltersInput!
  $pagination: PaginationInput!
) {
  inventoryItems(filters: $filters, pagination: $pagination) {
    items {
      # Your fields here
    }
    pagination {
      page
      pages
      limit
      count
      hasMore
    }
  }
}

Always refer to the specific query's documentation in the API reference to see its exact pagination structure and required parameters.

Pagination Parameters

Page Number

The page parameter specifies which page to retrieve. Pages are 1-indexed, meaning the first page is page 1.

# Get the first page
{ "page": 1 }

# Get the second page
{ "page": 2 }

Default: If not specified, defaults to page 1.

Limit (Page Size)

The limit parameter controls how many items are returned per page. The server may enforce maximum limits that vary by query.

Request a small number of items (10-20) that can be comfortably displayed on a single page. This provides:

• Better performance: Smaller payloads load faster
• Improved user experience: Users can see results immediately
• Reduced server load: Less data to process and transfer

Start with 10-20 items per page. You can adjust based on your UI needs.

Larger page sizes may:

• Take longer to load
• Consume more bandwidth
• Be subject to server-enforced maximum limits

The server will use your requested limit if it doesn't exceed the maximum allowed for that query. If your limit is too high, the server will enforce its maximum.

Sorting

You can sort results as part of the pagination request using sort and order:

{
  "pagination": {
    "page": 1,
    "limit": 20,
    "sort": "createdAt",
    "order": 1    # 1 = ascending, -1 = descending
  }
}

Note: Available sort fields depend on the specific query. Check the API reference for each endpoint to see supported sort fields.

Reading Pagination Metadata

Always read the pagination object in the response to understand the current state:

query GetPaginatedData($pagination: PaginationInput) {
  items(pagination: $pagination) {
    items {
      # Your fields here
    }
    pagination {
      page      # Current page number
      pages     # Total pages available
      limit     # Items per page
      count     # Total items across all pages
      hasMore   # Quick check: are there more pages?
      sort      # Current sort field (if applied)
      order     # Current sort order (if applied)
    }
  }
}

Key Fields Explained

• page: The current page number you're viewing
• pages: Total number of pages available (useful for building page number UI)
• limit: Number of items per page (may differ from your request if you exceeded max limit)
• count: Total number of items across all pages (useful for showing "X items total")
• hasMore: Boolean indicating if there are more pages after the current one (useful for "Load More" buttons)
• sort and order: Reflect the sorting applied to the current page

Navigation Patterns

Next Page Navigation

To get the next page, increment the page number:

# First page
{ "page": 1, "limit": 20 }

# Second page
{ "page": 2, "limit": 20 }

# Third page
{ "page": 3, "limit": 20 }

Previous Page Navigation

To get the previous page, decrement the page number (ensure it doesn't go below 1):

# Current page: 3
{ "page": 3, "limit": 20 }

# Previous page: 2
{ "page": 2, "limit": 20 }

Jump to Specific Page

You can jump directly to any page number:

# Jump to page 5
{ "page": 5, "limit": 20 }

Always validate that the requested page number doesn't exceed pages from the previous response.

Load More Pattern

Use the hasMore field to implement "Load More" functionality:

• Start with page 1
• After each request, check the hasMore field in the pagination response
• If hasMore is true, increment the page number and fetch the next page
• Continue until hasMore is false
• Append new items to your existing list as you load each page

Best Practices

• Always request pagination metadata - Include the pagination field in queries to get complete pagination information (page, pages, count, hasMore)
• Use appropriate page sizes - Request 10-20 items for most use cases. Request only what you can display on a single page. Larger pages (50+ items) may be slower and subject to server limits
• Check query-specific requirements - Before implementing pagination, check the API reference for the specific query's pagination input type, required parameters (like filters), supported sort fields, and any limitations
• Implement error handling - Validate page numbers (ensure at least 1), check page limits, handle invalid limits, handle empty results, and implement retry logic for network errors
• Cache pagination state - Store pagination metadata (current page, total pages, items per page, total count, sort parameters, hasMore flag) in application state to avoid unnecessary queries
• Maintain sort consistency - When navigating between pages, maintain the same sort parameters to ensure consistent results

Common Patterns

Page Number UI

Build a page number selector using the pages field:

• Use pagination.pages to determine how many page numbers to display
• Use pagination.page to highlight the current page
• Generate a list of page numbers from 1 to pages
• Make each page number clickable to navigate to that page
• Consider showing ellipsis (...) for large page counts to keep the UI clean

Infinite Scroll

Use hasMore to implement infinite scroll:

• Check pagination.hasMore before attempting to load more items
• When user scrolls near the bottom, increment the page number
• Fetch the next page using the incremented page number
• Append new items to the existing list without replacing current items
• Hide or disable the "Load More" button when hasMore is false

First/Last Page Navigation

Use pages to navigate to first or last page:

# First page
{ "page": 1, "limit": 20 }

# Last page (use pages from previous response)
{ "page": totalPages, "limit": 20 }

Error Handling

If you request a page number that doesn't exist:

• Page number too high: The API will typically return the last available page or an empty result set
• Invalid page number (0 or negative): The API will default to page 1
• Invalid limit: The API will use the default limit or maximum allowed limit

Always validate pagination responses and handle edge cases in your application.

Summary

• Common Ground uses page-based pagination (not cursor-based)
• Most queries use PaginationInput for pagination parameters, but some queries may have different structures
• Always check the API reference for each query's specific pagination approach
• Read the Pagination object in responses for complete metadata
• Pages are 1-indexed (first page is 1, not 0)
• Recommended page size: 10-20 items that can be displayed on a single page
• Always include pagination metadata in your queries
• Use hasMore for "Load More" functionality
• Use pages for page number navigation UI
• Different queries may require additional parameters (like filters) alongside pagination