Skip to main content
Marble API uses offset-based pagination for endpoints that return multiple items. Pagination metadata is included in every response to help you navigate through large datasets efficiently.

​
How Pagination Works

When you request a list of resources (like posts), the API automatically includes pagination information in the 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 -H "Authorization: YOUR_API_KEY" \
  "https://api.marblecms.com/v1/posts"

​
SDK Examples

Fetch posts with pagination options:
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

const result = await marble.posts.list({
  limit: 10,
  page: 1,
});
The SDK’s async iterable automatically handles fetching subsequent pages. If you only need a single page (e.g., for pagination controls), iterate once and break.
{
  "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://cdn.marblecms.com/images/cms-guide.webp",
      "description": "A comprehensive guide to integrating your CMS...",
      "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://cdn.marblecms.com/avatars/john.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 data 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.
Building Pagination UI: The pagination object in every response gives you everything needed for pagination controls: current page, total pages, and next/previous page numbers.

​
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 items, totalPages will be 0 and totalItems will be 0. The data array will be empty.