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 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:

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")