# Filtering

Filters allow to restrict the response of list endpoints. The available filter options for a supported list endpoint are returned by the filter options endpoint (e.g. /v3/assets/filter-options-v2).

## Get asset list

<mark style="color:green;">`POST`</mark> `https://api.akenza.io/v3/assets/list`

Filter the asset inventory

#### Query Parameters

| Name | Type     | Description                    |
| ---- | -------- | ------------------------------ |
| page | Interger | Page number (default 0)        |
| sort | String   | Sort string (field, direction) |

#### Request Body

| Name           | Type       | Description            |
| -------------- | ---------- | ---------------------- |
| organizationId | String     | Id of the organization |
| workspaceIds   | List       | List of workspace ids  |
| expression     | Expression | Filter expression      |
| search         | String     | Search string          |

{% tabs %}
{% tab title="200: OK List of assets" %}

{% endtab %}
{% endtabs %}

Endpoints that support the filter format described on this page:

* :white\_check\_mark: get asset list (/v3/assets/list)

## Filter options request

The filter options endpoint response contains information about the supported fields, their type, and supported predicates.

### Filter options

The filter options part contains all filterable fields. Each option provides the applicable filterTypes and can list available values.&#x20;

### Definitions

The definitions define the supported predicates based on the filterType.&#x20;

### Supported Predicates

The supported predicates contain the supported predicates by filterType.

### Predicates

Depending on the predicate a different amount of values are expected.

<table><thead><tr><th width="290">Predicate</th><th width="168">Number of values</th><th>Explanation</th></tr></thead><tbody><tr><td>EQUALS</td><td>1</td><td>This predicate checks for an exact match. For strings, it is case-insensitive</td></tr><tr><td>NOT_EQUALS</td><td>1</td><td>This predicate returns the inverse of EQUALS including null values</td></tr><tr><td>IN</td><td>1+</td><td>This predicate checks if one field value matches one of the values</td></tr><tr><td>NOT_IN</td><td>1+</td><td>This predicate returns the inverse of in</td></tr><tr><td>LESS_THAN</td><td>1</td><td>This predicate checks if the field value is less than the value</td></tr><tr><td>LESS_THAN_OR_EQUALS</td><td>1</td><td>This predicate checks if the field value is less than or equal to the value</td></tr><tr><td>LESS_THAN</td><td>1</td><td>This predicate checks if the field value is greater than the value</td></tr><tr><td>GREATER_THAN_OR_EQUALS</td><td>1</td><td>This predicate checks if the field value is greater than or equal to the value</td></tr><tr><td>BETWEEN</td><td>2</td><td>This predicate checks if the field value is between the two provided values. The order of values will automatically be ensured</td></tr><tr><td>CONTAINS_ALL</td><td>1+</td><td>This predicate checks that the list field value contains all values</td></tr><tr><td>CONTAINS_NONE</td><td>1+</td><td>Works like NOT_IN but is used for list fields</td></tr><tr><td>CONTAINS_ANY</td><td>1+</td><td>Works like IN but is used for list fields</td></tr><tr><td>CONTAINS</td><td>1</td><td>This predicate checks if a string contains a given value</td></tr><tr><td>STARTS_WITH</td><td>1</td><td>This predicate checks if a string starts with a given value</td></tr><tr><td>ENDS_WITH</td><td>1</td><td>This predicate checks if a string ends with a given value</td></tr><tr><td>BEFORE</td><td>1</td><td>checks if a date is before the given value</td></tr><tr><td>AFTER</td><td>1</td><td>checks if a date is after the given value</td></tr><tr><td>IS_NULL</td><td>0</td><td>checks if a field value is not set </td></tr><tr><td>IS_NOT_NULL</td><td>0</td><td>checks if a field value is set</td></tr></tbody></table>

## Filter Expressions

There are two constructs that can be set as an expression, the expression list and a Filter.

A filter is has three fields, the field name, a predicate and a list of values. The amount of values differ by the used predicate.

```json
{
    "field" : "id",
    "predicate" : "IN",
    "values": [
         "6600000000000000",
         "6600000000000001",
         "6600000000000002"
     ]
}
```

An expression list is used to combine multiple expressions and contains only two fields the operator and the a list of expressions. The operator which defines how the containing expressions are combined, it can be ether AND or OR. The expressions list has a max depth of 3.

```json
{
  "operator": "AND",
  "expressions": [
    {
      "operator": "OR",
      "expressions": [
        ...
      ]
    },
    {
      "operator": "FILTER",
      "field": "uplinkMetrics.timestamp",
      "predicate": "BETWEEN",
      "values": [
        1693815659321,
        1693815359321
      ]
    },
    ...
  ]
}
```

Example:

```json
{
    "search": "abc",
    "organizationId": "280000000000000",
    "expression": {
        "operator": "AND",
        "expressions": [
            {
                "field": "id",
                "predicate": "IN",
                "values": [
                    "0200000000000000",
                    "0200000000000001",
                    "0200000000000002"
                ]
            },
            {
                "operator": "OR",
                "expressions": [
                    {
                        "field": "name",
                        "predicate": "STARTS_WITH",
                        "values": [
                            "someething"
                        ]
                    },
                    {
                        "field": "name",
                        "predicate": "ENDS_WITH",
                        "values": [
                            "else"
                        ]
                    }
                ]
            },
            {
                "field": "customFields",
                "predicate": "EQUALS",
                "stringValues": ["Zurich"],
                "customFieldName": "Location"
            },
            {
              "field": "tags.name",
              "values": ["test"],
              "predicate": "CONTAINS_ALL"
            }
        ]
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akenza.io/akenza.io/get-started/reference/api-documentation/filtering.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.