Filtering & sorting¶
List endpoints accept query parameters to narrow and order results. The exact filters available on each endpoint are listed in the API reference — this page explains the syntax they share.
Filtering¶
Filters are plain query parameters. Combine as many as you like; they're ANDed together.
Misspelled filters are ignored
The API ignores a query parameter it does not declare, so a misspelled filter returns an unfiltered list with 200. Check the parameter names in the API reference for each endpoint.
Filter kinds¶
| Kind | Example | Matches |
|---|---|---|
| Equality | ?role=admin |
Exact value. |
| Boolean | ?is_archived=false |
true / false. |
| Reference | ?user=8f3a… |
A related resource by its public_id. |
| Free-text search | ?search=python |
Case-insensitive substring over a resource's searchable fields (usually name). |
| Date/time lower bound | ?created__gte=2026-01-01T00:00:00Z |
On or after (__gte). |
| Date/time upper bound | ?due_date__lte=2026-03-31 |
On or before (__lte). |
Datetime bounds take ISO-8601 timestamps; date bounds (like due_date__gte) take YYYY-MM-DD.
These are not RQL
List filtering uses simple, fixed query parameters — one parameter per filterable field. There is no general RQL expression language on list endpoints. RQL appears in exactly one place in the API: the expression field of a saved report.
Examples¶
Find a user by email:
Active members of a group, newest first:
A user's overdue, still-open assignments:
Events from one series, created this quarter:
Tracks filed in one channel (every content list, and /content-items/, takes channel):
Events that start in October. starts_at__gte and starts_at__lte compare against the event's starts_at, the start of its earliest timeslot, as a point in time. starts_at in a response carries the venue's offset, and any offset is accepted here: an event at 09:00 in a +02:00 venue matches 2026-10-01T09:00:00+02:00 and 2026-10-01T07:00:00Z alike. A timestamp without an offset is read as UTC:
Reads and writes use different time conventions
Filters and responses use real instants. Timeslot writes still take the venue's wall-clock time labeled as UTC (see the starts_at field on timeslot create and update).
Video and article content created in a date window:
GET /api/v2/content-items/?content_type=video&created__gte=2026-01-01T00:00:00Z&created__lte=2026-06-30T23:59:59Z
Sorting¶
Use ordering with a field name. Prefix with - for descending. Some endpoints accept a comma-separated list for tie-breaking:
The sortable fields per endpoint are listed in the API reference. Common ones are name, created, and modified.
Pagination¶
Filtering and sorting compose with pagination (page, page_size). See Conventions → Pagination. The meta.total_count in the response reflects the count after filters are applied, so it's a reliable basis for paging through a filtered set.
Saved reports (segments)¶
When you need a reusable, expression-based filter — the kind of compound condition that doesn't fit a handful of query parameters — create a saved report. Its expression field is written in RQL (Resource Query Language), for example:
Run the report through its /results/ sub-resource to get the matching rows; any extra query parameters you pass to /results/ are ANDed with the stored expression. Saved reports are the only surface where you author RQL directly — everywhere else, use the query parameters above. See the Saved Reports tag in the API reference.