Pagination - PublishBuddy

List endpoints return a paginated response. Pagination is offset-based and predictable.

Request

Pass page (1-indexed) and optionally per_page (defaults to 25, capped per endpoint):

curl "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/posts?page=3&per_page=50" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN"

Response shape

Paginated responses include a meta object alongside data:

{
  "data": [ /* up to per_page items */ ],
  "meta": {
    "current_page": 3,
    "from": 101,
    "to": 150,
    "per_page": 50,
    "last_page": 12,
    "total": 587,
    "path": "https://api.publishbuddy.com/v1/workspaces/xxx/posts"
  },
  "links": {
    "first": "https://api.publishbuddy.com/v1/workspaces/xxx/posts?page=1",
    "last":  "https://api.publishbuddy.com/v1/workspaces/xxx/posts?page=12",
    "prev":  "https://api.publishbuddy.com/v1/workspaces/xxx/posts?page=2",
    "next":  "https://api.publishbuddy.com/v1/workspaces/xxx/posts?page=4"
  }
}

Stop iterating when meta.current_page === meta.last_page (or when links.next is null).
meta.total is the total count across all pages — useful for “X of Y” UI counters.

Iterating in code

async function* paginate(url, token) {
  let page = 1;
  while (true) {
    const res = await fetch(`${url}?page=${page}&per_page=100`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const body = await res.json();
    for (const item of body.data) yield item;
    if (page >= body.meta.last_page) return;
    page += 1;
  }
}

for await (const post of paginate(
  `https://api.publishbuddy.com/v1/workspaces/${workspaceId}/posts`,
  token
)) {
  // ...
}

def paginate(url, token, params=None):
    page = 1
    while True:
        res = requests.get(
            url,
            headers={'Authorization': f'Bearer {token}'},
            params={**(params or {}), 'page': page, 'per_page': 100},
        )
        res.raise_for_status()
        body = res.json()
        yield from body['data']
        if page >= body['meta']['last_page']:
            return
        page += 1

Sensible per_page values

Use case	Recommended `per_page`
Interactive UI (table view)	25 — fast and matches the dashboard.
Sync / export job	100 — fewer round-trips.

Don’t go above 100 — it’s the hard cap on most list endpoints, and larger pages don’t speed things up because the underlying database queries are tuned for that size.

Stable ordering

List endpoints return results in a deterministic order (most recently updated first, or most recently published — endpoint-dependent). Pagination is stable as long as no new items are inserted at the top mid-iteration. For long-running exports, consider also filtering by from / to date range to keep the result set stable.