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.

Pagination properties

limit · integer

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

currentPage · integer

The current page number being returned.

nextPage · integer | null

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

previousPage · 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 PaginationCustom LimitSpecific Page

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

cURLSDK

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

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

Fetch 5 items per page:

cURLSDK

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:

cURLSDK

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:

fetchSDK

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.

Tip

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

Tip

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

Note

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

Tip

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.

How Pagination Works

Query Parameters

Pagination Response

Request Examples

Building Pagination Controls

Best Practices

Error Handling

Hat das auf deinem Setup funktioniert?