Skip to content

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.

GET /api/v2/content-items/?content_type=video&is_archived=false

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:

GET /api/v2/users/?email=jane.doe@acme.com

Active members of a group, newest first:

GET /api/v2/users/?group=4b1c…&is_active=true&ordering=-date_joined

A user's overdue, still-open assignments:

GET /api/v2/assignments/?user=8f3a…&is_overdue=true&state=in_progress

Events from one series, created this quarter:

GET /api/v2/events/?event_series_id=6ba7…&created__gte=2026-04-01T00:00:00Z

Tracks filed in one channel (every content list, and /content-items/, takes channel):

GET /api/v2/tracks/?channel=9f8e…

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:

GET /api/v2/events/?starts_at__gte=2026-10-01T00:00:00Z&starts_at__lte=2026-10-31T23:59:59Z

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:

GET /api/v2/assignments/?modified__gte=2026-10-01T09:30:00Z&ordering=modified

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

  1. First run. Read the whole list with ordering=modified. Keep the largest modified you saw as your cursor.
  2. Later runs. Request modified__gte=<cursor>&ordering=modified&page_size=100. Upsert every record by public_id, then move the cursor to the last record's modified and ask again. Stop when a page comes back shorter than page_size.
  3. Ties. If a whole page shares one modified value, take page=2, page=3, … with the same cursor until the value changes. Bulk changes can stamp many records with the same instant.
  4. Overlap. Start each run a few minutes before the stored cursor. PlusPlus stamps modified when 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 modified of their own. Adding, moving or removing an item moves the track's modified, 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:

GET /api/v2/users/?ordering=-date_joined,name

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:

and(eq(is_active,true),ilike(name,*smith*))

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.