Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Filter Syntax


To limit the results that are returned in an API retrieval request (HTTP GET), most JSA API endpoints that return lists of resources support the filter parameter.

The filter parameter syntax is consistent for all endpoints that support it. Refer to the documentation for the endpoint to determine if the filter parameter applies to it. Any limitations for the filter syntax are included in that endpoint's description. You are reminded that query parameters must be double URL encoded before they are sent.

Comparison Operators

The filter comparison operators table describes the comparison operators that you can use as part of the filter parameter.

Table 1: Filter Comparison Operators



Example Filter Syntax


Equality between the identifier and the specified value returned.

To find offenses where status=CLOSED:

GET /api/siem/offenses?filter=status%3DCLOSED


Identifier is greater than the specified value.

To find offenses where credibility > 3:



Identifier is less than the specified value.

To find offenses where magnitude < 9:



Identifier is less than or equal to the specified value.

To find offenses where id <= 1004:



Identifier is greater than or equal to the specified value.

To find offenses where scanProfileId >= 3:





Identifier is not equal to the specified value.

The following examples filters all IDs that are not equal to 5:





Identifier is equal to at least one of the specified values in the list.

id in (1001,1111,1200):


not in

Identifier is not equal to any of the specified values in the list.

id not in (1001,1002,1003):


between … and ...

Identifier is between 2 specified values.

id between 0 and 3:


not between … and …

Identifier is not between 2 specified values.

id not between 30 and 31:


is null

Identifier is null.

assigned_to is null:


is not null

Identifier is not null.

assigned_to is not null:


Null Values and Comparison Operators

When the field that you filtered on has a 'null' value, comparison operators behave in the following ways:

  • "=", ">", ">=", "<", "<=", "IN", and "BETWEEN" operators always return false

  • "!=", "<>", "^=", "NOT BETWEEN", and "NOT IN" always return true

The best way to test for null values is to use the "is null" or "is not null" operators.

Logical Operators

Use the logical operators OR, AND, and NOT to perform logical operations on subexpressions. The following table provides examples of how to use logical operators in filters.





Performs a logical OR operation on the 2 subexpressions. The subexpressions might be comparison nodes or other logical nodes.

assigned_to is not null OR id = 111:




Performs a logical AND operation on the 2 sub-expressions. The sub-expressions might be comparison nodes or other logical nodes.

assigned_to is not null AND id = 111:




Performs a logical NOT operation on the subexpression.

protected =true and not id in (111,112,113)



Specifying JSON Fields for Comparisons

The following table explains how to specify JSON fields for use with comparison operators in filters.

JSON field example



{ "name": "Proprietary Data", "element_type": "ALN" }

When you apply a filter to a field directly in the object that is returned, the field is specified by name.

name = "Proprietary Data"

GET /api/reference_data/sets?filter=name%20


{ "description": "String", "duration": { "days": 42, "hours": 42, "minutes": 42, "months": 42, "seconds": 42.5, "years": 42 } }

When you apply a filter to a field nested inside a sub object use brackets to specify the inner field.

duration(days) >= 20




For simple JSON types where there is no field label, such as strings, numbers or Boolean, use the . operator.

.= events

GET /api/ariel/databases?filter=.%3D%20events

Specifying String and Numeric Values in Filters

When you filter on string that have values with non-alphanumeric characters, you must wrap the target string in quotation marks. When you filter on numeric values, the numeric values can follow these conditions:

  • Start with a leading + or - sign.

  • Contain or start with a decimal point

  • Include an exponent using e notation.

Filtering Complex Objects by Using the CONTAINS Operator

You filter complex objects by using the CONTAINS operator. You use the CONTAINS operator to test the contents of lists or maps. On the left side of the operator, is an identifier that is in the standard format, for example x(y(z)). The identifier must refer to an element that is a list, map, or collection. On the right side, of the operator is an expression that specifies how the objects in the list must be matched. There are two basic uses for the CONTAINS operator:

  • The list that is examined contains simple elements like strings or numbers

  • The list contains complex objects.

  • Lists that contain simple types--For lists that contain simple types such as strings or numbers, the expression is a value of the same type. For single comparisons, no brackets are required

    To request only asset saved searches that have ftp as the string in the filter's value field:

    GET /api/asset_model/saved_searches?filter=filters%20


    To request assets where interfaces contains the IP address “”:

    GET /api/asset_model/assets?filter=interfaces%20contains%


  • Lists that contain complex objects--For lists that contain complex objects, the expression is a complete filter expression for the objects within the list. This subfilter expression uses the same syntax as any other filter. You can use any operator in the subfilter to test sublists inside the original list. Identifiers in this expression are relative to the objects in the list that the CONTAINS operator is operating on. In complex subfilter expressions, brackets are required.

    To request only assets that have a field value = 14 and the Greater than operator , apply the filter filters contains (value = 14 or operator = "Greater than"). This filter returns the first and the last elements in the list.

    GET /api/asset_model/saved_searches?filter=filters%20


    To find offenses that contain source addresses that have ID values less than 3 apply the following filter:

    GET /api/siem/offenses?filter=source_address_ids%20contains%20(.%3C3)

The LIKE Operator

Use the LIKE operator to retrieve partial string matches.

The LIKE operator uses the following format: identifier like "expression". Quotation marks around the expression is mandatory. Single and double quotation marks are supported. The LIKE keyword does case-sensitive matching.

The following wildcard characters are supported. If you use wildcard characters in a string, you must use escape them.

Wildcard character



Matches a string of zero or more characters


Matches any single character

You can combine the wildcards in the same expression. For example, to find the reference set whose name ends with Data and begins with H:

GET /api/reference_data/sets?filter=name%20like%20%22H_%25Data%22