Pagination

{
  "posts": [
    {
      "id": "post_abc",
      "title": "August 24-31, 2026 Release",
      "slug": "august-24-31-2026-release",
      "content": "<p>This week brought meaningful improvements to scheduling and mobile responsiveness.</p>",
      "htmlUrl": null,
      "markdown": "This week brought meaningful improvements to scheduling and mobile responsiveness.",
      "rawHtml": null,
      "recommendations": null,
      "contentType": "changelog",
      "sourceMetadata": null,
      "status": "published",
      "createdAt": "2026-08-31T11:32:54.082Z",
      "updatedAt": "2026-08-31T11:32:54.082Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 1
  },
  "organization": {
    "id": "org_123",
    "slug": "acme",
    "name": "Acme",
    "logo": null
  }
}

{
  "posts": [
    {
      "id": "post_abc",
      "title": "August 24-31, 2026 Release",
      "slug": "august-24-31-2026-release",
      "content": "<p>This week brought meaningful improvements to scheduling and mobile responsiveness.</p>",
      "htmlUrl": null,
      "markdown": "This week brought meaningful improvements to scheduling and mobile responsiveness.",
      "rawHtml": null,
      "recommendations": null,
      "contentType": "changelog",
      "sourceMetadata": null,
      "status": "published",
      "createdAt": "2026-08-31T11:32:54.082Z",
      "updatedAt": "2026-08-31T11:32:54.082Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 1
  },
  "organization": {
    "id": "org_123",
    "slug": "acme",
    "name": "Acme",
    "logo": null
  }
}

Notra uses page-based pagination on the list endpoints that can grow without bound. Each takes page and limit query parameters and returns a pagination object for building paging controls.

Paginated endpoints

Endpoint	Default `limit`	Max `limit`	Items key
`GET /v1/posts`	10	100	`posts`
`GET /v1/feedback`	25	100	`feedback`
`GET /v1/projects/{projectId}/geo/scans`	20	100	`scans`

Other list endpoints are not paginated, so brand identities, integrations, schedules, event triggers, chats, skills, GEO projects, prompts, sequences, competitors and briefs return the full list. GEO traffic endpoints (traffic/log, traffic/journeys, traffic/pages) and GET /v2/agent-chats accept a limit only and return the most recent items. Visibility and traffic reads use a days or from/to window instead.

Query parameters

integer

default:"10"

Items per page. Range: 1 to 100. The default depends on the endpoint, as the table above shows.

integer

default:"1"

The page number to retrieve, starting at 1.

The API rejects out-of-range values instead of clamping them, so limit=500 or page=0 returns 400 with an error such as limit: Too big: expected number to be <=100. GET /v1/posts also accepts sort (asc or desc by creation date, default desc) and the comma-separated filters status, contentType and brandIdentityId. GET /v1/feedback accepts status, kind and projectId.

Pagination response

Every paginated response includes a pagination object:

object

Metadata about the current page and navigation options.

Show Pagination properties

integer

The number of items per page (matches your query parameter or the endpoint default).

integer

The page number being returned.

integer | null

The next page number, or null when there is no next page.

integer | null

The previous page number, or null on page 1.

integer

The total number of pages, which is always at least 1, even when there are no items.

integer

The total number of items across all pages after the API applies filters.

Request examples

Default pagination
Custom limit
Specific page
Feedback

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,
});

Page through new feedback, 50 per page:

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/feedback?status=new&limit=50&page=1"

Building pagination controls

Build navigation controls from the pagination object:

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`;

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": "post_abc",
      "title": "August 24-31, 2026 Release",
      "slug": "august-24-31-2026-release",
      "content": "<p>This week brought meaningful improvements to scheduling and mobile responsiveness.</p>",
      "htmlUrl": null,
      "markdown": "This week brought meaningful improvements to scheduling and mobile responsiveness.",
      "rawHtml": null,
      "recommendations": null,
      "contentType": "changelog",
      "sourceMetadata": null,
      "status": "published",
      "createdAt": "2026-08-31T11:32:54.082Z",
      "updatedAt": "2026-08-31T11:32:54.082Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 1
  },
  "organization": {
    "id": "org_123",
    "slug": "acme",
    "name": "Acme",
    "logo": null
  }
}

{
  "posts": [],
  "pagination": {
    "limit": 10,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 0
  },
  "organization": {
    "id": "org_123",
    "slug": "acme",
    "name": "Acme",
    "logo": null
  }
}

Best practices

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

Use smaller page sizes (5 to 20 items), especially for mobile clients.

Always handle an empty items array in your UI.

Use nextPage and previousPage to enable or disable navigation buttons, since each is null when there is no page in that direction.

Edge cases

Page past the end

Requesting a page beyond totalPages is not an error, and the API returns 200 with an empty items array, nextPage: null and previousPage set to the page before the one you asked for. Stop paging when nextPage is null instead of guessing page numbers.

Invalid limit or page

The API rejects values outside the allowed range with 400 and an error message that names the parameter. Non-numeric values fail the same way, and the API never clamps values.

Empty datasets

When there are no items, totalItems is 0, totalPages is 1, the items array is empty and both nextPage and previousPage are null.

Filters and totals

totalItems and totalPages reflect the filtered result set. On GET /v1/posts, omitting status returns only published posts, so pass status=draft,published to count drafts too.

Last modified on October 8, 2026

Getting Started

Developer Tools

Guides

Webhooks

Endpoints

Paginated endpoints

Query parameters

Request examples

Best practices

Edge cases

​Paginated endpoints

​Query parameters

​Pagination response

​Request examples

​Building pagination controls

​Best practices

​Edge cases

Paginated endpoints

Query parameters

Pagination response

Request examples

Building pagination controls

Best practices

Edge cases