Chapter 6. Filtering in the API

You can use additional query string parameters used to filter the list of results returned to those matching a given value. You can only use fields and relations that exist in the database for filtering. Ensure that any special characters in the specified value are URL-encoded. For example:

?field=value%20xyz

?field=value%20xyz

Fields can also span relations, only for fields and relationships defined in the database:

?other__field=value

?other__field=value

To exclude results matching certain criteria, prefix the field parameter with not__:

?not__field=value

?not__field=value

By default, all query string filters are AND’ed together, so only the results matching all filters are returned. To combine results matching any one of multiple criteria, prefix each query string parameter with or__:

?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue

?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue

The default AND filtering applies all filters simultaneously to each related object being filtered across database relationships. The chain filter instead applies filters separately for each related object. To use this, prefix the query string parameter with chain__:

?chain__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&chain__related__field2=othervalue

?chain__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&chain__related__field2=othervalue

If you write the first query as ?relatedfield=value&relatedfield2=othervalue, it returns only the primary objects where the same related object satisfied both conditions. As written by using the chain filter, it would return the intersection of primary objects matching each condition.

You can use field lookups for more advanced queries, by appending the lookup to the field name:

?field__lookup=value

?field__lookup=value

The following field lookups are supported:

For example, ?created__gte=2023-01-01 provides a list of items created after 1/1/2023.

You can specify null values as None or Null (both case-insensitive), though we recommend using the isnull lookup to explicitly check for null values.

You can specify lists (for the in lookup) as a comma-separated list of values. Filtering based on the requesting user’s level of access by query string parameter:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
...

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
...