Filtering

Some endpoints that return top-level collections of data and are used for statistics-related requests allow filtering of returned items.

Enum-Based Filtering

By default, filters are enum-based (for example, “published|archived|draft”), where items that match the filter are exact matches to the provided filter value.

Example

If a resource has a status field with possible values (published, archived, draft), filtering with ?filter=status:draft will only return items where status is exactly draft.

GET /v2/content?filter.state=draft

Equals-Based Filtering

Some endpoints allow eq (equals-based) filtering, which returns records that equal the given value.

Endpoint examples that allow this filter:

• List users.

Example

The GET /users endpoint allows you to filter by a user’s username or by a user’s role.

Filtering by username will return an exact user, whereas role will return all users with that role assigned to them.

To filter users by the role type of member, this filter looks like: role eq "member"

Expanded out: GET /scim/v2/Users?filter=userRole eq "member"

Timestamp Filtering

Resources with timestamp properties offer range-based filters including .from and .to. Timestamp filters accept either timestamps (2018-05-01T17:36:52) or datestamps (2018-05-01) in ISO 8601 format. Datestamp values are assumed to be in UTC.

Datestamp Example

GET /content?filter.created_at.from=2023-06-01&filter.created_at.to=2023-12-31

• Retrieves content created between June 1, 2023, and December 31, 2023.
• Only the date is considered (time defaults to 00:00:00 UTC).

Timestamp (ISO 8601) Example

GET /content?filter.created_at.from=2023-06-01T08:30:00Z&filter.created_at.to=2023-12-31T18:45:00Z

• Retrieves content created between June 1, 2023, at 08:30 AM UTC and December 31, 2023, at 6:45 PM UTC.
• Includes exact time filtering.

Any Property Filtering

When possible, endpoints allow for filtering items by any property provided in the resource. Exceptions apply for cases such as long text properties.

Multiple Property Filtering

When multiple filters are used in a single request, the filters are combined with an AND logic. Use the & character between filters to apply and logic.

Example

To filter /content using AND logic with filter.content_type and filter.visibility, your GET request would look like this:

GET/content?filter.content_type=article&filter.visibility=public

Multiple Value Filtering

When a filter allows multiple values, you can provide them as a comma-separated list or an array of strings. By default, the filter applies an OR logic (match ANY), meaning at least one value must match for the item to be included in the results.

Example

GET /content?filter.content_type=article,video

• Returns content where content_type is either "article" or "video".

Filtering Errors

Filter values provided in a request that cannot be parsed or do not match expected formats result in a 400 Bad Request response.