Pagination and cursors
Page through posts with cursor and nextCursor, and through events with since and before.
Lists come back newest first. Posts page with a cursor. Events page by time.
Posts
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 25 | Posts per page, 1 to 100. |
cursor | string | The nextCursor from the previous page. | |
status | string | draft, scheduled, published or pending_approval. | |
platform | string | Only posts for this network, like x or linkedin. |
The response has the page and the cursor for the next one:
{
"posts": [
{
"id": "cmhjz4w2p0001l708xq3kd9vb",
"platform": "linkedin",
"status": "draft",
"text": "We shipped our public API today. Three things we learned writing the docs first.",
"thread": [
"We shipped our public API today. Three things we learned writing the docs first."
],
"firstComment": null,
"mediaCount": 0,
"scheduledAt": null,
"publishedAt": null,
"url": null,
"failure": null,
"createdAt": "2026-11-04T13:05:12.481Z",
"updatedAt": "2026-11-04T13:05:12.481Z"
}
],
"nextCursor": "cmhjy8b1k0004l708m2rt6qcn"
}nextCursor is null on the last page. Pass it back unchanged as cursor, with the same filters:
const headers = { Authorization: `Bearer ${process.env.POSTEL_API_KEY}` };
const drafts = [];
let cursor = null;
do {
const url = new URL("https://www.postel.app/api/v1/posts");
url.searchParams.set("status", "draft");
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, { headers });
const page = await res.json();
drafts.push(...page.posts);
cursor = page.nextCursor;
} while (cursor);
console.log(drafts.length);Posts are ordered by when they were created, newest first. A cursor is a post id. Treat it as opaque.
Events
Events page by time instead of a cursor, because you usually want what happened since your last poll.
| Parameter | Type | Default | Description |
|---|---|---|---|
type | string | required | post.published, post.failed, draft.ready or viral.new. |
since | string | ISO 8601 time with a timezone. Only events after it. | |
before | string | ISO 8601 time with a timezone. Only events at or before it, to page back. | |
limit | integer | 25 | Events per page, 1 to 100. |
To page back through a full page, pass the oldest occurredAt you got as before. That event comes back again on the next page, because before includes it, so dedupe on id. Polling events has a full poll loop.