Skip to main content

​
Overview

The MTB Backend API uses page-based pagination to handle large datasets efficiently. All list endpoints return paginated results with metadata about the total number of items and pages.

​
Pagination Parameters

Control pagination using the pagination query parameters:
ParameterTypeDescriptionDefaultMaximum
pagination[page]integerPage number to retrieve1-
pagination[pageSize]integerNumber of items per page25100
The default page size is 25 items, with a maximum of 100 items per page as configured in the API settings.

​
Basic Usage

# Returns first 25 items
curl "https://api.example.com/api/articles"

​
Pagination Response Format

Paginated responses include both data and metadata: 
{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "Article Title",
        "description": "Article description",
        "createdAt": "2026-03-01T10:00:00.000Z",
        "updatedAt": "2026-03-02T15:30:00.000Z"
      }
    }
    // ... more items
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 4,
      "total": 100
    }
  }
}

​
Response Fields

​
data
array
Array of resources for the current page
​
meta
object
Metadata container
​
pagination
object
Pagination information
​
page
number
Current page number
​
pageSize
number
Number of items per page
​
pageCount
number
Total number of pages available
​
total
number
Total number of items across all pages

​
Pagination Limits

The API enforces the following limits (configured in config/api.ts): 
export default {
  rest: {
    defaultLimit: 25,
    maxLimit: 100,
    withCount: true,
  },
};
  • Default limit: 25 items per page
  • Maximum limit: 100 items per page
  • Count included: Total count is always included in responses (withCount: true)
Requesting a pageSize greater than 100 will automatically be capped at the maximum limit of 100 items.

​
Iterating Through Pages

Use the pagination metadata to iterate through all pages: 
async function fetchAllArticles() {
  const allArticles = [];
  let currentPage = 1;
  let pageCount = 1;
  
  while (currentPage <= pageCount) {
    const response = await fetch(
      `https://api.example.com/api/articles?pagination[page]=${currentPage}&pagination[pageSize]=100`
    );
    const json = await response.json();
    
    allArticles.push(...json.data);
    pageCount = json.meta.pagination.pageCount;
    currentPage++;
  }
  
  return allArticles;
}

​
Combining with Filters and Sorting

Pagination works seamlessly with filtering and sorting: 
curl "https://api.example.com/api/articles?\
  filters[status][$eq]=published&\
  sort=publishedAt:desc&\
  pagination[page]=1&\
  pagination[pageSize]=50"
When combining pagination with filters, the total and pageCount values reflect the filtered results, not the entire dataset.

​
Disabling Pagination

For small datasets, you can disable pagination to retrieve all results at once: 
curl "https://api.example.com/api/articles?pagination[pageSize]=-1"
Use with caution: Disabling pagination on large datasets can impact performance and response times. This is only recommended for collections with a known small number of items.

​
Best Practices

Choose an appropriate page size based on your use case:
  • Small page sizes (10-25): Better for UI pagination, faster initial response
  • Large page sizes (50-100): More efficient for data processing, fewer requests
  • Maximum page size (100): Use when fetching all data in batches
Always check pagination metadata before processing:
if (json.meta.pagination.pageCount === 0) {
  // No results found
  console.log("No articles available");
} else if (json.meta.pagination.page > json.meta.pagination.pageCount) {
  // Requested page exceeds available pages
  console.log("Page not found");
}
For frequently accessed pages, consider caching:
  • Cache individual pages with appropriate TTL
  • Invalidate cache when data changes
  • Store pagination metadata separately
Performance tip: For large datasets, use a combination of:
  • Maximum page size (pageSize=100)
  • Specific field selection (fields[0]=id&fields[1]=title)
  • Targeted filters to reduce the result set
This minimizes the number of requests and response payload size.

Build docs developers (and LLMs) love

Get started for freeTalk to us