Pagination and Filters

Every list pages the same way, and every time-based list takes the same time filter. This page also covers sort and include.

PaginationCopy Anchor Link

Every list returns data, nextCursor and hasMore.

{
  "data": [{ "id": "pst_3c8a2d6e91b44f7a8e250d6b4c1f9a73" }],
  "nextCursor": "eyJrZXkiOjE4MDM...",
  "hasMore": true
}

Pass nextCursor as cursor until hasMore is false. Send the cursor unchanged, and keep the other parameters the same.

Leave cursor out to start over. On lists such as posts, accounts and media, a changed or foreign cursor returns 400 INVALID_CURSOR.

import { Configuration, PostsApi } from "@onepostly/sdk";

const postsApi = new PostsApi(
  new Configuration({ accessToken: process.env.ONEPOSTLY_API_KEY })
);

let cursor: string | undefined;
do {
  const page = await postsApi.listPosts({ status: "published", limit: 100, cursor });
  for (const post of page.data) {
    console.log(post.id, post.url);
  }
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Page SizeCopy Anchor Link

limit sets the page size of a list. A value below 1 or above the maximum for that list returns 400 VALIDATION_ERROR.

Comments, reviews and account media follow the platform's page size. Each endpoint in the API Reference lists its limit.

Time FiltersCopy Anchor Link

Time-based lists and reports take since and until.

A date alone or a time without a zone returns 400 VALIDATION_ERROR. A since after until returns 400 INVALID_RANGE.

Since until is exclusive, one window ends where the next begins. For all of August, send since=2026-08-01T00:00:00Z and until=2026-09-01T00:00:00Z. Encode + as %2B in a query string.

Deliveries are kept for your plan's log retention. A since older than that starts at the oldest delivery that is still kept.

SortingCopy Anchor Link

Some lists take sort, a field and a direction, such as created_desc for newest first. Every other list has a fixed order, mostly newest first.

Each * is desc or asc. See List Posts for the metric sorts.

IncludeCopy Anchor Link

Some lists add extras when you ask with include, a comma-separated list.

total counts every match across all pages. An unknown value returns 400 VALIDATION_ERROR with the accepted values.

ErrorsCopy Anchor Link

Other codes are in Errors.