# Filter list requests

`list` methods retrieve multiple resources of a set type. The `filter` query
parameter lets you give criteria that the retrieved resources must meet.

## Filter structure

`filter` parameter values are strings. These strings are made up of one or more
criteria. Criteria are joined by **`AND`** or **`OR`** operators.

A single criterion has the form `{field} {operator} {value}`. Here's an example:

```
  entityStatus="ENTITY_STATUS_ACTIVE"
```

Filter strings are limited to 500 characters. If your string is too long:

- Break up the logic into separate strings. Make a `list` call with each filter string. Combine the results to make a single list.
- Remove criteria from the filter string. Use the removed criteria to filter the retrieved resources locally.

Wrap values for a criterion in quotes.

Make sure that your filter strings are encoded for use in a URL when making API
calls directly.

See the [Join criteria](https://developers.google.com/display-video/api/guides/concepts/optimization/filter-lists#join_criteria) section for more on filter string
structure.

## Filter criteria

Each list method supports certain filter criteria. The description for the
method's `filter` parameter lists these criteria. Filter criteria are often a
subset of the retrieved resource's fields.

Each criterion supports one or more operators:

| **Comparable operators** ||
|---|---|
| `EQUALS (=)` | Field is equal to the given value. Example: `entityStatus="ENTITY_STATUS_ACTIVE"` |
| `LESS THAN OR EQUAL TO (<=)` | Field is less than or equal to the given value. Often used to filter by a date or datetime. Example: `updateTime<="2023-04-01T12:00:00Z"` |
| `GREATER THAN OR EQUAL TO (>=)` | Field is greater than or equal to the given value. Often used to filter by a date or datetime. Example: `updateTime>="2023-03-01T12:00:00Z"` |
| `HAS (:)` | Field contains the given value. If the field is a string, it will check if the given value is a substring. If the field is an array, it will check the array for the given value. Example: `lineItemIds:"1234"` |

If a criterion doesn't specify an operator, it only supports `EQUALS (=)`.

A criterion will note if it needs a special format.

### Join criteria

Join multiple criteria to further restrict the `list` response.

Join criteria with logical operators **`AND`** and **`OR`** . Each `list` method
specifies which are supported. Some methods only support filters with one
criterion.

Consider these limits when using multiple criteria:

> [!NOTE]
> **Note:** These examples are for use in a line item [`list`](https://developers.google.com/display-video/api/reference/rest/current/advertisers.lineItems/list) request.

| **Limitations and examples** ||
|---|---|
| `AND` must combine restrictions, or groups of restrictions, that filter different fields, or that filter the same field differently. | `updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")` |
| `OR` must combine individual restrictions that filter by the same field. | `(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")` |
| `OR` can't combine two groups of restrictions. Use multiple `list` requests with different filter values instead. | The following two filter strings must be used in separate requests and **can't** be combined using the `OR` operator: - `(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")` - `(lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")` |
| Parentheses may be implied to group restrictions even if they are not included. | The filter string `updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"` is interpreted as `updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")` |