Pagination
Page through large collections with cursor-based pagination.
All list endpoints in the Palmframe API use cursor-based pagination. Cursors are stable even as records are created or deleted, which makes them reliable for iterating over large collections.
Request parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Number of items to return per page. Between 1 and 100. Defaults to 25. |
cursor | string | Opaque cursor from a previous response's next_cursor. Omit for the first page. |
List envelope
Every list endpoint returns the same envelope shape:
{
"object": "list",
"data": [
{ "object": "post", "id": "post_abc123" },
{ "object": "post", "id": "post_def456" }
],
"pagination": {
"limit": 25,
"has_more": true,
"next_cursor": "cursor_ZmZmZg"
}
}| Field | Type | Description |
|---|---|---|
object | string | Always "list". |
data | array | The items on this page. |
pagination.limit | integer | The effective page size that was applied. |
pagination.has_more | boolean | true if more items are available after this page. |
pagination.next_cursor | string | null | Pass as cursor to fetch the next page. null when has_more is false. |
Fetching the first page
curl "https://palmframe.com/api/v1/posts?limit=50" \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"Looping until has_more is false
To collect an entire collection, keep passing next_cursor back as cursor
until has_more becomes false:
const BASE = "https://palmframe.com/api/v1";
const key = process.env.PALMFRAME_API_KEY!;
async function listAllSubscribers() {
const subscribers = [];
let cursor: string | null = null;
do {
const url = new URL(`${BASE}/subscribers`);
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, {
headers: { Authorization: `Bearer ${key}` },
});
const page = await res.json();
subscribers.push(...page.data);
cursor = page.pagination.has_more ? page.pagination.next_cursor : null;
} while (cursor);
return subscribers;
}Use the largest page size you can
Requesting limit=100 minimizes the number of round trips when exporting a
full collection.