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.

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

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:

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, 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:

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.