Filtering, sorting and paging

The list parameters: typed JSON filters with operators, text search, sorting, choosing fields, counting, and cursor or offset paging.

Last updated September 17, 2026

On this page

Listing a table takes these query parameters. They combine freely.

Parameter	Meaning
`q`	A JSON filter (below), URL-encoded
`search`	Case-insensitive text to look for across every text field
`sort_by`	A field name; prefix with `-` for descending, e.g. `-created_date`
`fields`	Comma-separated fields to return. `id` is always included
`limit`	Records per page, up to 5,000 (500 with a publishable key). Default 100
`cursor`	The `X-Next-Cursor` of the previous page
`skip`	Offset paging. Cursors are better for anything deep
`count`	`true` adds an `X-Total-Count` header with the number of matching records
`deleted`	Secret keys only: `only` for deleted records, `include` for both

Filters

A filter is a JSON object. A plain value means equality; an object with an operator compares.

JSON

{"status": "open"}
{"amount": {"$gte": 10000}}
{"status": {"$in": ["open", "pending"]}, "created_date": {"$gte": "2026-06-01"}}
{"$or": [{"priority": "high"}, {"overdue": true}]}
{"address.city": "Brooklyn"}

Operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains (text fields), $exists.
Comparisons are typed by the field: numbers compare as numbers, dates take ISO dates.
Combine with $and or $or. Dotted names reach into JSON fields.
An unknown field name is refused, with the table's real fields named in the message.

Shell

curl -G https://<your app address>/api/entities/Order \
  -H "X-Api-Key: pxa_sk_..." \
  --data-urlencode 'q={"status":"open","total":{"$gte":100}}' \
  --data-urlencode 'sort_by=-created_date' --data-urlencode 'limit=50' --data-urlencode 'count=true'

Sorting

One field, typed: numbers sort numerically, dates chronologically. Ties break on id, so an order is stable between pages. A publishable key cannot sort or filter by created_by_id.

Paging

When there is another page the answer carries X-Next-Cursor and a Link header with rel="next". Pass the cursor back as ?cursor= with the same sort. Cursors are stable under inserts and cost nothing to jump deep; they work when sorting by created_date, updated_date or id (the default sort qualifies). skip works for shallow paging and cannot be combined with a cursor.

Counting

GET /api/entities/<E>/count?q=... returns {"count": n} without fetching rows.

Was this page helpful?