Skip to main content

​
What is pagination?

Marble API uses offset-based pagination for endpoints that return multiple items. Pagination allows you to retrieve large datasets in smaller, manageable chunks rather than loading everything at once.

​
How pagination works in Marble API

When you request a list of resources (like posts, categories, or tags), the API automatically includes pagination metadata in every response. This allows you to:
  • Control how many items are returned per request
  • Navigate to specific pages
  • Understand the total size of the dataset
  • Build pagination UI components

​
Query Parameters

​
limit
integer
default:"10"
The maximum number of items to return per page.Range: 1-200 items per page
​
page
integer
default:"1"
The page number to retrieve. Pages start at 1.Minimum: 1

​
Pagination Response

Every paginated response includes a pagination object with the following fields:
​
pagination
object
Metadata about the current page and navigation options.

​
Request Examples

Get the first page with default limit (10 items):
cURL
curl -X GET 'https://api.marblecms.com/v1/YOUR_WORKSPACE_ID/posts'

{
  "posts": [
    {
      "id": "post_abc123def456",
      "slug": "getting-started-with-cms-integration",
      "title": "Getting Started with CMS Integration",
      "content": "<p>Learn how to integrate your content management system...</p>",
      "coverImage": "https://images.example.com/media/cms-integration-guide.webp",
      "description": "A comprehensive guide to integrating your CMS with modern web frameworks...",
      "publishedAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:22:33.456Z",
      "attribution": null,
      "authors": [
        {
          "id": "author_xyz789",
          "name": "John Smith",
          "image": "https://images.example.com/avatars/john-smith.jpg"
        }
      ],
      "category": {
        "id": "cat_tutorials123",
        "name": "Tutorials",
        "slug": "tutorials"
      },
      "tags": [
        {
          "id": "tag_integration456",
          "name": "Integration",
          "slug": "integration"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 5,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 2
  }
}

{
  "posts": [],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 0,
    "totalItems": 0
  }
}

{
  "error": "Invalid page number",
  "details": {
    "message": "Page 2 does not exist.",
    "totalPages": 1,
    "requestedPage": 2
  }
}

​
Paginated Endpoints

The following endpoints support pagination:

Posts

Get all published posts with pagination support.

Categories

Browse all content categories with pagination.

Authors

List all authors with their associated content.

Tags

Retrieve all content tags with pagination.

​
Best Practices

Optimize Performance: Use smaller page sizes (5-20 items) for better performance, especially on mobile devices.
Handle Empty Results: Always check if the posts array is empty and handle the empty state in your UI.
Navigation Logic: Use nextPage and previousPage values to build navigation controls. These fields will be null when navigation in that direction isn’t possible.

​
Error Handling

When you request a page that doesn’t exist, the API returns a structured error response:
{
  "error": "Invalid page number",
  "details": {
    "message": "Page 2 does not exist.",
    "totalPages": 1,
    "requestedPage": 2
  }
}
Always check for the error field in your response before processing pagination data.
  • Values below 1 will default to 1
  • Values above 200 will be capped at 200
  • Non-numeric values will default to 10
When there are no posts, totalPages will be 0 and totalItems will be 0. The posts array will be empty.