Skip to content
BuildBase
HTTP API menu

Pagination and filtering

How BuildBase lists page with page and limit, the filters each list takes, and the filter, sort and projection syntax of the organization API.

In short

A list can be long, so BuildBase answers it a page at a time. You ask for a page number and how many items you want on it, and the answer says whether there is another page. Most lists also take filters, such as status=active, that narrow what comes back.

Paging a list in the app API

The examples call the cloud, https://api.console.buildbase.app; a self-hosted install uses its own base URL. App API lists that page take two query parameters:

ParameterTypeAllowedWhat it does
pageinteger1 or more; at most 10000 on most listsWhich page, starting at 1
limitinteger1 to 100How many items on the page
curl -s "https://api.console.buildbase.app/api/v1/public/me/orders?page=2&limit=25" \
  -H "x-session-id: $BUILDBASE_SESSION_ID"

The answer carries the page's items and how to reach the next one; /me/orders, for one, answers docs with page, limit and hasNextPage. Read until the answer says there is no next page:

list-all-orders.ts
const base = 'https://api.console.buildbase.app/api/v1/public/me/orders';
let page = 1;
let more = true;

while (more) {
  const res = await fetch(`${base}?page=${page}&limit=100`, {
    headers: { 'x-session-id': process.env.BUILDBASE_SESSION_ID! },
  });
  const body = await res.json();
  console.log(body);
  more = Boolean(body.hasNextPage);
  page += 1;
}

Each list's reference page says which parameters it takes, their limits, and the names of the fields in its answer. Some lists take neither parameter and answer every row, and a list that did not page before never starts paging by default, so code written against it keeps working (Versioning and changes).

Filtering in the app API

App API lists filter with named query parameters, each listed with its allowed values on the operation's reference page and in the OpenAPI spec. The common ones:

ParameterExampleSeen on
statusstatus=activeAffiliates, subscriptions, bookings, credit holds
q or searchq=lampItems
from, tofrom=2026-11-01&to=2026-11-30Bookings, usage logs
sortsort=-startBookings: start or -start (newest first)
An id: itemId, programId, orderId...programId=665f1c2e9b1d4a0012ab34cdLists inside a program, an order or an item

A value outside the allowed set is a 400 that names the field in path.

Paging and filtering the organization API

Organization API lists (/api/blogs, /api/users and their siblings, called with an API key) share one list handler with a richer syntax:

ParameterExampleWhat it does
$page$page=2The page, from 1
$limit$limit=50Items per page. Default 10 unless the list sets its own; at most 500 (a larger value is capped)
filterfilter[published]=trueMatch fields. Also accepted as JSON text: filter={"published":true}
sortsort[createdAt]=-1 or sort=-createdAtOrder by a field, -1 or - for descending
projectionprojection[title]=1Only these fields, 1 to include or 0 to leave out. At most 50 fields
paginationpagination=falseAsks for every row: answered with the largest page, 500, and hasNextPage says when there is more
curl -s -G "https://api.console.buildbase.app/api/blogs" \
  -H "Authorization: Bearer $BUILDBASE_API_TOKEN" \
  --data-urlencode 'filter[published]=true' \
  --data-urlencode 'sort[createdAt]=-1' \
  --data-urlencode '$limit=20'

The answer is a page object:

{
  "docs": [],
  "totalDocs": 0,
  "limit": 20,
  "page": 1,
  "totalPages": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

A filter may use these operators and no others: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or, $nor, $not, $exists, $type, $all, $elemMatch, $size, $regex (at most 200 characters) and $options. Another operator, text that is not a JSON object, or a projection that names a hidden field is a 400.

curl -s -G "https://api.console.buildbase.app/api/blogs" \
  -H "Authorization: Bearer $BUILDBASE_API_TOKEN" \
  --data-urlencode 'filter={"createdAt":{"$gte":"2026-11-01"}}'

Next steps