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
Assignments that changed since your last sync, oldest change first:
Incremental sync¶
To keep a copy of PlusPlus data current without re-reading everything, ask only for what changed since your last run. These lists take modified__gte and modified__lte, and sort by modified:
- Every content list:
/content-items/,/articles/,/videos/,/guides/,/courses/,/links/,/programs/,/tracks/,/scheduled-tracks/,/collections/,/events/,/event-series/, and a collection's/collections/{public_id}/items/. /assignments/,/enrollments/,/course-registrations/and/users/./channels/,/groups/and/tags/./surveys/,/survey-relationships/and/survey-responses/.
Each record in those lists carries its modified timestamp. Both bounds are inclusive, and a timestamp without an offset is read as UTC. In a query string, write a positive offset as %2B02:00, or use Z. A bare + decodes to a space, and the request fails with 422.
The sync loop¶
- First run. Read the whole list with
ordering=modified. Keep the largestmodifiedyou saw as your cursor. - Later runs. Request
modified__gte=<cursor>&ordering=modified&page_size=100. Upsert every record bypublic_id, then move the cursor to the last record'smodifiedand ask again. Stop when a page comes back shorter thanpage_size. - Ties. If a whole page shares one
modifiedvalue, takepage=2,page=3, … with the same cursor until the value changes. Bulk changes can stamp many records with the same instant. - Overlap. Start each run a few minutes before the stored cursor. PlusPlus stamps
modifiedwhen it writes a change, which can be a moment before the change commits.
Because the bounds are inclusive and runs overlap, you see some records twice. Upserting by public_id makes that harmless.
Move the cursor, not the page
Walking page=1, 2, 3, … over a moving data set can skip a record: when a record you already read changes during the walk, every record after it shifts one place earlier. Asking again from the last modified instead keeps every change in view. The one exception is the tie walk in step 3: a record that changes while you page through a tie can still shift a record past you. A later run whose overlap reaches back to that instant, or a periodic full re-read, catches it.
What modified does not cover¶
modified moves when the record itself is written. Some changes live elsewhere and leave it alone:
- Content items: tags, facilitators, access groups, event timeslots (and so
starts_at/ends_at), a guide's package versions, and the engagement counters (total_assignments,completed_assignments_count,avg_feedback_rating). - Track items: they have no
modifiedof their own. Adding, moving or removing an item moves the track'smodified, so fetch/tracks/{public_id}/track-items/again for each track that changed. - Assignments and enrollments: states that follow from the clock rather than a write, such as becoming overdue or expired.
Some records also leave a list without changing: deleted records, expired assignments, and the assignments, enrollments and course registrations of deactivated users are no longer returned. Subscribe to webhooks (for example content_item.deleted and assignment.deleted) to hear about removals, and re-read the full list from time to time to catch anything the gaps above let through.
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. Pages after the first may report a count up to a minute old, so stop paging on a short page rather than on total_count.
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.