Pagination

Notra uses offset-based pagination for list endpoints. Each response includes a pagination object so you can build paging controls in your UI.

How Pagination Works

When you request a list of posts, the response includes pagination metadata so you can:

Control how many items each request returns
Move between pages
Know how many total items exist
Build clear pagination controls

Query Parameters

limit

integer

default:"10"

The maximum number of items to return per page. Range: 1-100 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:

pagination

object

Metadata about the current page and navigation options.

Show Pagination properties

limit

integer

The number of items requested per page (matches your query parameter).

currentPage

integer

The current page number being returned.

integer | null

The next page number, or null if you’re on the last page.

integer | null

The previous page number, or null if you’re on the first page.

totalPages

integer

The total number of pages available.

totalItems

integer

The total number of items across all pages.

Request Examples

Default Pagination
Custom Limit
Specific Page

Fetch the first page with the default limit (10):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/posts"

const result = await notra.content.listPosts();

Fetch 5 items per page:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/posts?limit=5"

const result = await notra.content.listPosts({
  limit: 5,
});

Fetch page 2 with 5 items per page:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/posts?page=2&limit=5"

const result = await notra.content.listPosts({
  page: 2,
  limit: 5,
});

Building Pagination Controls

Use the pagination object to build navigation controls:

const response = await fetch(
  "https://api.usenotra.com/v1/posts?page=1&limit=10",
  {
    headers: {
      Authorization: `Bearer ${process.env.NOTRA_API_KEY}`,
    },
  }
);

const data = await response.json();
const { pagination } = data;

const canGoBack = pagination.previousPage !== null;
const canGoForward = pagination.nextPage !== null;
const pageInfo = `Page ${pagination.currentPage} of ${pagination.totalPages}`;
const itemCount = `${pagination.totalItems} total items`;

import type { Pagination } from "@usenotra/sdk/models/operations";

const result = await notra.content.listPosts({
  page: 1,
  limit: 10,
});

const { pagination } = result;

const canGoBack = pagination.previousPage !== null;
const canGoForward = pagination.nextPage !== null;
const pageInfo = `Page ${pagination.currentPage} of ${pagination.totalPages}`;
const itemCount = `${pagination.totalItems} total items`;

{
  "posts": [
    {
      "id": "YOUR_POST_ID",
      "title": "February 12-19, 2026 Release",
      "content": "<p>This week brought meaningful improvements to organization management, scheduling, and mobile responsiveness.</p><h2>Highlights</h2><h3>Organization membership unification with server validation</h3><p>Leave and delete operations now use consistent, validated server logic with atomic operations to prevent race conditions on concurrent requests.</p>",
      "markdown": "This week brought meaningful improvements to organization management, scheduling, and mobile responsiveness.\n\n## Highlights\n\n### Organization membership unification with server validation\nLeave and delete operations now use consistent, validated server logic with atomic operations to prevent race conditions on concurrent requests.",
      "contentType": "changelog",
      "sourceMetadata": null,
      "status": "published",
      "createdAt": "2026-02-19T11:32:54.082Z",
      "updatedAt": "2026-02-19T11:32:54.082Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 1
  }
}

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

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

Best Practices

Use a distinct cache key for each combination of page, limit, sort, status, and contentType.
Invalidate paginated list caches after post updates, deletes, and completed generation jobs.
For a fuller strategy, see Caching.

Performance: Use smaller page sizes (5-20 items), especially for mobile clients.

Empty states: Always handle posts: [] in your UI.

Navigation: Use nextPage and previousPage to enable or disable buttons. These values are null when movement is not possible.

UI state: pagination already contains everything you need for page state: current page, total pages, next, and previous.

Error Handling

Invalid page number

If you request a page that does not exist, the API returns an error response:

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

Check for an error field before reading pagination values.

Invalid limit value

Values below 1 default to 1
Values above 100 are capped at 100
Non-numeric values default to 10

Empty datasets

When there are no items, totalPages is 0, totalItems is 0, and posts is an empty array.

Getting Started

Guides

Webhooks

Endpoints

Query Parameters

Request Examples

Best Practices

Error Handling

​How Pagination Works

​Query Parameters

​Pagination Response

​Request Examples

​Building Pagination Controls

​Best Practices

​Error Handling

How Pagination Works

Query Parameters

Pagination Response

Request Examples

Building Pagination Controls

Best Practices

Error Handling