Pagination

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

Request

Pass page (1-indexed) and optionally per_page (defaults to 20 for posts and media, 50 for profiles; capped at 100):

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

Response shape

Paginated responses include meta and links objects alongside data:

{
  "data": [ /* up to per_page items */ ],
  "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"
  },
  "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": [ /* page links for building a pager */ ]
  }
}

Stop iterating when meta.current_page equals 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.
The posts list adds meta.status_counts: the number of posts per status (waiting, publishing, published, failed, needs_approval, draft) for the current filters, independent of the page you are on.

Which endpoints paginate:

Endpoint	Paginated
`GET /workspaces/{workspace}/posts`	Yes
`GET /workspaces/{workspace}/media_contents`	Yes
`GET /workspaces/{workspace}/profiles`	Yes
`GET /analytics/profiles/{profile}`	The `posts` array inside `data` is paginated; the totals are not
`GET /workspaces`, folders, hashtags, best times, profile metrics	No, the full result is returned

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 close to what the dashboard shows.
Sync or export job	100, fewer round trips.

Do not go above 100. It is the hard cap on every list endpoint, and the request fails validation with 422 if you exceed it.

Ordering

Posts are ordered by their planned publish time (scheduled_for), earliest first. There is one exception: when published is the only status you filter on, the default is the actual publish time (published_at), newest first. filters[sort_by] replaces the default order:

`filters[sort_by]`	Order
`published_at`	Actual publish time, newest first. Suits “recently published” views.
`likes`, `comments`, `shares`, `reach`, `engagements`	The named metric from each post’s latest analytics snapshot, highest first. Posts with no analytics yet come last.

Any other value is 422. Profiles accept a sort parameter: name, -name, created_at, or -created_at (a leading - means descending). The default is created_at, oldest first. Media is returned in the same order the dashboard’s library shows it.

Filtering by date

Pagination is stable as long as nothing is inserted ahead of your cursor mid-iteration. For long-running exports of posts, narrow the set with filters[publish_range][] (planned publish time) or filters[date_range][] (actual publish time) so the result set does not shift under you. Each range takes exactly two YYYY-MM-DD dates, the first and the last day to include. The -g flag stops curl from treating the brackets as a pattern:

curl -g "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/posts?status=published&filters[date_range][]=2026-04-01&filters[date_range][]=2026-04-30" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

The days run from the start of the first date to the end of the last, read in the timezone set in the token user’s settings, UTC when none is set. Unlike scheduled_for, which ignores the account’s timezone, these filters use it. Posts with no value in the filtered column are left out, so filters[date_range][] only ever returns published posts, and filters[publish_range][] leaves out posts that have no planned time yet. A range that is not exactly two YYYY-MM-DD dates is 422.

Getting started

Core concepts

How-to guides

API essentials

Request

Response shape

Iterating in code

Sensible per_page values

Ordering

Filtering by date

​Request

​Response shape

​Iterating in code

​Sensible per_page values

​Ordering

​Filtering by date

Request

Response shape

Iterating in code

Sensible per_page values

Ordering

Filtering by date