Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Filtering in the API

The system recognizes a collection as a "queryset". You can filter this by using various operators.

Learn how to use query parameters within the REST API URL to filter resources based on criteria such as exact matches, partial string containment (__contains), integer casting (__int), and many fields simultaneously.

Procedure

  • To find groups that contain the name "car", use the following: 

    http://<gateway server name>/api/controller/v2/groups/?name__contains=car
    Copy to Clipboard Toggle word wrap

  • To find an exact match, use the following: 

    http://<gateway server name>/api/controller/v2/groups/?name=car
    Copy to Clipboard Toggle word wrap

  • If a resource is of an integer type, you must add \_\_int to the end to cast your string input value to an integer, such as the following: 

    http://<gateway server name>/api/controller/v2/arbitrary_resource/?x__int=5
    Copy to Clipboard Toggle word wrap

  • You can query related resources with the following: 

    http://<gateway server name>/api/gateway/v1/users/?first_name__icontains=kim
    Copy to Clipboard Toggle word wrap

    This returns all users with names that include the string "kim" in them.

  • You can also filter against many fields at once: 

    http://<gateway server name>/api/controller/v2/groups/?name__icontains=test&has_active_failures=false
    Copy to Clipboard Toggle word wrap

    This finds all groups containing the name "test" that have no active failures.

    You can also watch the API as the UI is being used to see how it is filtering on various criteria.

Additional resources

6.1. Advanced queries in the API
Copy link

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
Copy to Clipboard Toggle word wrap

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

?other__field=value
Copy to Clipboard Toggle word wrap

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

?not__field=value
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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.

6.2. Field lookups
Copy link

Field lookups allow you to filter API results based on specific criteria. You can use field lookups for more advanced queries, by appending the lookup to the field name: 

?field__lookup=value
Copy to Clipboard Toggle word wrap

The following field lookups are supported:

  • exact: Exact match (default lookup if not specified, see the following note for more information).
  • iexact: Case-insensitive version of exact.
  • contains: Field contains value.
  • icontains: Case-insensitive version of contains.
  • startswith: Field starts with value.
  • istartswith: Case-insensitive version of startswith.
  • endswith: Field ends with value.
  • iendswith: Case-insensitive version of endswith.
  • regex: Field matches the given regular expression.
  • iregex: Case-insensitive version of regular expression.
  • gt: Greater than comparison.
  • gte: Greater than or equal to comparison.
  • lt: Less than comparison.
  • lte: Less than or equal to comparison.
  • isnull: Check whether the given field or related object is null; expects a boolean value.
  • in: Check whether the given field’s value is present in the list provided; expects a list of items.
  • You can specify boolean values as True or 1 for true, False or 0 for false (both case-insensitive).

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:

  • role_level: Level of role to filter on, such as admin_role
Note

Earlier releases of Ansible Automation Platform returned queries with _exact results by default. As a workaround, set the limit to ?limit_exact for the default filter. For example, /api/controller/v2/jobs/?limit_exact=example.domain.com results in: 

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
...
Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat