# 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](https://api.console.buildbase.app); a self-hosted install uses [its own base URL](/http-api/base-urls). App API lists that page take two query parameters:

| Parameter | Type    | Allowed                                | What it does               |
| --------- | ------- | -------------------------------------- | -------------------------- |
| `page`    | integer | 1 or more; at most 10000 on most lists | Which page, starting at 1  |
| `limit`   | integer | 1 to 100                               | How many items on the page |

```bash
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:

```typescript title="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](/http-api/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](/http-api/openapi). The common ones:

| Parameter                                  | Example                              | Seen on                                           |
| ------------------------------------------ | ------------------------------------ | ------------------------------------------------- |
| `status`                                   | `status=active`                      | Affiliates, subscriptions, bookings, credit holds |
| `q` or `search`                            | `q=lamp`                             | Items                                             |
| `from`, `to`                               | `from=2026-11-01&to=2026-11-30`      | Bookings, usage logs                              |
| `sort`                                     | `sort=-start`                        | Bookings: `start` or `-start` (newest first)      |
| An id: `itemId`, `programId`, `orderId`... | `programId=665f1c2e9b1d4a0012ab34cd` | Lists 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:

| Parameter    | Example                                   | What it does                                                                                       |
| ------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `$page`      | `$page=2`                                 | The page, from 1                                                                                   |
| `$limit`     | `$limit=50`                               | Items per page. Default 10 unless the list sets its own; at most 500 (a larger value is capped)    |
| `filter`     | `filter[published]=true`                  | Match fields. Also accepted as JSON text: `filter={"published":true}`                              |
| `sort`       | `sort[createdAt]=-1` or `sort=-createdAt` | Order by a field, `-1` or `-` for descending                                                       |
| `projection` | `projection[title]=1`                     | Only these fields, `1` to include or `0` to leave out. At most 50 fields                           |
| `pagination` | `pagination=false`                        | Asks for every row: answered with the largest page, 500, and `hasNextPage` says when there is more |

```bash
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:

```json
{
  "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`.

```bash
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

- [Rate limits](/http-api/rate-limits) - read a long list without hitting one.
- [HTTP API errors](/http-api/errors) - what a refused filter answers.
- [Delivering content](/content/delivering-content) - read and cache content lists with a key.
