Learn how to use the filter parameter to get filtered results from REST API queries made in the Wowza Video™ service. The filter parameter restricts the data that gets returned to one or more values associated with a field.
About filters
To use the filter query parameter, you'll send a GET request to an endpoint that supports filtering and append a query URL with a two-part expression that specifies the field on which to filter and the logic (comparison operator) to use to filter. You can use as many filters as you want, combining them with an ampersand (&). Order doesn't matter; multiple filters are additive.
Use the syntax ?filter[n][field]=value&filter[n][comparison operator]=value where n is a zero-based index. For example, to return all transcoders that aren't actively running (all transcoders whose state isn't started):
curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/transcoders?filter[0][field]=state&filter[0][in]=starting,resetting,stopping,stopped"
Filtering by date and time
Queries for created_at or updated_at need to be made in Coordinated Universal Time (UTC) format. There are online converters available to help you convert your local time to UTC. Your dates should be formatted as follows: YYYY-DD-MMT HH:MM:SSZ using 24-hour clock ("military") time and including the T and Z.
Note: In UTC the T marks the end of the date portion and the Z represents zero UTC time offset.
Examples of UTC:
- May 25, 2022 at 1:07:49 PM = 2022-05-25T13:07:49.000Z
- March 14, 2015 at 8:25:20 PM = 2015-03-14T20:25:20.000Z
- August 29, 2019 at at 3:47 AM = 2019-08-29T03:47:53.000Z
Supported filters
The following filters are supported.
| Filter | Description |
| eq | == |
| neq | != |
| gt | > |
| gte | >= |
| lt | < |
| lte | <= |
| in | One in the set equals the value. Takes a comma-separated string of values. |
| nin | None in the set equal the value. Takes a comma-separated string of values. |
| like | Contains the value. You can use * or % as a wildcard. |
| sort | In ascending (asc) or descending (desc) order. Example: filter[0][sort] = desc |
Endpoints and fields that support filters
The following endpoints support the filter parameter in the GET request:
- /assets
Note: The /assets endpoint has additional functionality for using ?query expressions.
See the Query parameter for /assets endpoint to learn more. - /live_streams
- /real_time
- /recordings
- /schedules
- /stream_sources
- /stream_targets
- /transcoders
- /vod_streams
For the endpoints listed above, you can filter on the following fields, where they exist:
- id
- name
- state
- created_at
- updated_at
- playback_enabled (vod streams only)
Sample requests
Below are some sample filter requests to get you started.
Transcoders
Return only transcoders whose state is stopped:
curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/transcoders?filter[0][field]=state&filter[0][eq]=stopped"
Return only transcoders that are started and have the name MyTranscoder or MyOtherTranscoder:
curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/transcoders?filter[0][field]=state&filter[0][eq]=started&filter[1][field]=name&filter[1][in]=MyTranscoder,MyOtherTranscoder"
Live streams
Return live streams created after March 14, 2022 at midnight UTC.
curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}"
"${WV_HOST}/api/${WV_VERSION}/live_streams??filter[0][field]=created_at&filter[0][gte]=2022-03-14T00:00:00.000Z"
Return live streams with specified ids. You can enter as many ids as you'd like to filter by separated by commas.
curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/live_streams?filter[0][field]=id&filter[0][in]=DF2GmmPH,c5FNnMp0"
Recordings
Return all recordings whose state is not completed.
curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/recordings?filter[0][field]=state&filter[1][nin]=completed"
Schedules
Return all schedules with a created_at date older than January 1, 2021 sorted in descending order.
curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
{WV_HOST}/api/${WV_VERSION}/schedules?filter[0][field]=created_at&filter[0][lte]=2021-01-01T00:00:00Z&filter[1][field]=created_at&filter[1][sort]=desc"
VOD streams
Return VOD streams that have the state of playback_enabled set to false.
curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/vod_streams?filter[0][field]=playback_enabled&filter[0][eq]=false"
Query parameter for /assets endpoint
Prior to version 1.10 of the REST API, the /assets endpoint only supported query expressions as a way of filtering results. With version 1.10 and later, the /assets endpoint supports both the filter parameter like our other endpoints do, described above, as well as the query parameter.
You can build a ?query expression with the following syntax ?query=[x]with optional additional parameters as shown below. Partial queries are allowed.
Note: Only tags that are applied to active assets are queried. Tags which only exist on deleted assets will not be returned.
When you execute a ?query expression, the following fields are searched:
- title
- tag_list
The following parameters are also valid, but optional:
- sort_column: defaults to created_at
- sort_direction: desc (default) or asc
- page: defaults to 1
- per_page: defaults to 15
- state: completed, failed, no_video, processing, queued, uploading
Sample requests
Return all failed assets.
curl -X GET -g \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/assets?state=failed
All completed assets including the title "sample" with 30 results per page.
curl -X GET -g \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/assets?sort_direction=desc&sort_column=created_at&per_page=30&page=1&state=completed&query=sample
All assets with the tag "promotion".
curl -X GET -g \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/assets?query=promotion
