Filtering data
A JSON filter expression consists of dictionaries and lists which can contain other dictionaries and lists. Every such an object is a logical condition.
A set of conditions in a dictionary is conjuncted by the and logical expression.
A set of conditions in a list is conjuncted by the or logical expression.
Special dictionary keys or , and, and not may be used as explicit logical operators.
Value followed by the or key should be a list that contains conditions conjuncted by the or logical operator. Value followed by the and key should also be a list that contains conditions. In this case, such conditions conjuncted by the and logical operator.
Value followed by the not key should be a condition whose value is reverted in this case.
Any dictionary key prefixed by the dash - is ignored, and the following value should be a condition that is merged to the expression containing such a key.
Dictionary keys that differ from the special are used as lookup expressions as it is described in the Django documentation https://docs.djangoproject.com/en/2.2/ref/models/lookups/. Field names similar to special keys are forbidden, so we always can separate special keys from field names.
Django lookup expression consists of a field name, which can be extended by field names following through relations, and some number of transforms, like lower, first3chars, reversed, etc., and lookups, like exact, icontains gt, etc. Field names, transforms, and lookups are separated by double underscore which is a standard lookup expression separator in Django. For example: project__name__first3chars__icontains.
Value followed by the lookup expression is a search value. It may be a simple value, or even JSON value if the correspondent field is a JSON field. Some lookup expressions, such as __in, assume a list as a search value.
The string search value can be started with commercial at @. Such value means a reference to the field, as described for the F-expression here https://docs.djangoproject.com/en/2.2/ref/models/expressions/#django.db.models.F.
The search value may be None. Then the correspondent lookup expression is extended by the __isnull and search value appears to be True.
Examples and more detailed reference can be found here: QuerySet Filter
Choosing only certain fields
Furthermore, if the consuming application doesn't need entire objects, you can retrieve only specific fields using the only_fields selector.
Examples
How can I retrieve only bookings where booking.user_accepted_offer_at is not null?
/api/v2/booking/?user_accepted_offer_at__isnull=false&no_total_count=true
/api/v2/booking/?user_accepted_offer_at__isnull=false&no_total_count=true&only_fields=user_accepted_offer_at,id
How do you retrieve subscription passes with a start date later than a specified value (e.g., 2025-09-23T04:26:22)?
/api/v2/subscriptionpass?pass_start__gt=2025-09-23T04:26:22
How to retrieve simulation results for a specific date only, sorted by creation time?
/api/v2/simulation?project={{project_id}}&order_by=-created_at&start_time__date=2024-10-01
How do I filter specific fields from the response? The following example includes only selected fields, while the second request excludes a single field.
/api/v2/simulation?project={{project_id}}&only_fields=id,start_time,name
/api/v2/simulation?project={{project_id}}&exclude_fields=id