Iterating collections and narrowing them with filters and ordering
Every collection endpoint in Orgo (GET /api/v1/users, GET /api/v1/events, GET /api/v1/payments, …) supports the same pagination, filtering, and ordering query parameters. Once you learn the pattern on one endpoint, the rest follow the same shape.
Defaults: 30 items per page, maximum 100 per page.
Query parameter
Purpose
Default
page
1-indexed page number
1
itemsPerPage
Page size (capped at 100)
30
pagination
Set to false to disable pagination, where allowed
true
# First page, default sizeGET /api/v1/users# Second page, 50 items per pageGET /api/v1/users?page=2&itemsPerPage=50# As many items as the endpoint allows in one goGET /api/v1/countries?pagination=false
pagination=false is only honored on endpoints flagged for it (mostly small reference lists like countries and counties). On large collections it is ignored — you must paginate.
import requestsurl = "https://acme.orgo.space/api/v1/users?itemsPerPage=100"headers = {"Api-Token": "..."}while url: resp = requests.get(url, headers=headers).json() for user in resp["hydra:member"]: process(user) url = resp.get("hydra:view", {}).get("hydra:next") if url and not url.startswith("http"): # Hydra returns relative URLs; join against the host url = f"https://acme.orgo.space{url}"
You do not get totals or next-page links — increment page until the response is shorter than itemsPerPage:
page = 1per_page = 100while True: resp = requests.get( f"https://acme.orgo.space/api/v1/users?page={page}&itemsPerPage={per_page}", headers={"Api-Token": "...", "Accept": "application/json"} ).json() for user in resp: process(user) if len(resp) < per_page: break page += 1
For long-running exports, prefer JSON-LD — hydra:totalItems lets you display progress and hydra:next is a stable signal that the server still has more rows.
Filters are query-string parameters. The available filters differ per resource and are listed under each endpoint’s Parameters section in the reference.
User and Contact resources expose a customFieldValues.value filter that targets the value column of the custom-fields table. Pair with customFieldValues.customField (the custom field IRI) to target a specific field:
GET /api/v1/users?customFieldValues.customField=/api/v1/custom_fields/8&customFieldValues.value=Vegetarian
Use order[field]=asc|desc. Order by multiple fields by repeating the parameter:
# Single field, descendingGET /api/v1/events?order[startDate]=desc# Two fields — first by status, then by nameGET /api/v1/events?order[status]=asc&order[name]=asc# By a related resource's fieldGET /api/v1/users?order[localCenter.name]=asc&order[lastName]=asc
The default order varies per resource (usually dateCreated descending for “feed” resources like Events and Newsletters, alphabetic for reference data).
Collection endpoints fetch and serialize each row’s full read group. For large datasets, prefer narrow filters before broad ones (?status=ACTIVE shrinks the row count before any extra joins).
itemsPerPage=100 is the maximum — larger requests return at most 100 and the rest must be paginated.
Sorting by a non-indexed column on a large collection can be slow. If a sort feels slow, check whether the column is documented as filterable — those are guaranteed indexed.
