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
listcall 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:
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:
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.OR
operator: -
(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") -
(lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
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")
