GET /api/v1/users, GET /api/v1/events, GET /api/v1/product_payments, …) supports the same pagination, filtering, and ordering query parameters. Once you learn the pattern on one endpoint, the rest follow the same shape. Which filters a given collection accepts is listed under that endpoint’s Parameters in the reference.
Pagination basics
The default page size is set per resource. Most collections use 30, users use 50, and a few reference lists are larger (countries use 1000). The reference shows the default under each endpoint’s
itemsPerPage parameter. Whatever the default, a request that asks for more than 100 with itemsPerPage gets at most 100.
page must be a positive whole number
A page of 0, a negative number, or a value that is not a number is a client error. The API answers 400 Bad Request, not 500:
page beyond the last page is not an error: you get an empty collection. Stop iterating when the collection is empty (or hydra:next is absent), not when you see an error.
pagination=false
Clients cannot switch pagination off in general. The cap exists so one request cannot pull a whole tenant’s data, so ?pagination=false is ignored on almost every collection. The few collections that opt in advertise a pagination parameter in the reference (events and units, for example). On everything else, paginate.
Iterating every page
The reliable way to iterate depends on which response format you accept.With JSON-LD (the default)
Followhydra:view.hydra:next until it is absent:
With plain JSON
You get no totals or next-page links. Incrementpage until the response is shorter than itemsPerPage:
Filtering
Filters are query-string parameters. The available filters differ per resource. Unknown parameters are ignored rather than rejected, so a misspelled filter returns the unfiltered collection. Check that the result shrank.Exact-value filter
ACTIVE). Several other statuses, such as event, payment, invoice, contract and vote statuses, are lowercase. Read the enum in the reference rather than guessing.
Filter by relation
For most relations, pass the related resource’s IRI:localCenter filter takes the numeric id, one value at a time, and answers 400 No Local Center with this id for an id that does not exist or is out of reach:
Multi-value (OR)
Where a filter advertises thename[] form in the reference, repeat the parameter to match any of several values:
Keyword search
User and event-like collections that support it take akeyword parameter. Check the endpoint for it, because the name differs on some resources (contacts use search, events use name):
Date range
Date filters use the[before], [after], [strictly_before], [strictly_after] modifiers on the date properties each resource names:
Presence
exists[property]=true|false tests whether a nullable property is set:
Custom-field filters
User collections acceptcustomFieldValues.field (the custom field) and customFieldValues.value (the stored value), which narrow to members who hold that value for that field:
Ordering
Useorder[field]=asc|desc. Order by several fields by repeating the parameter. Only the fields listed under the endpoint’s parameters can be ordered:
Combining filters, ordering, and pagination
Stack them with&:
?name=annual%20meeting). Most HTTP clients do this for you.
Performance notes
- Collection endpoints fetch and serialize each row’s full read group. For large datasets, apply narrow filters first (
?status=ACTIVEshrinks the row count before anything else happens). itemsPerPage=100is the maximum, so use it for exports to keep the request count low.- Sorting by a non-indexed column on a large collection can be slow. Stick to the
order[...]fields the reference lists.
Related
- Content types: the Hydra envelope shape used in JSON-LD pagination
- Errors: the
400a badpageproduces

